Garbage Collection in LibGit2

So this is as much as I could glean.

Memory models

Reference counted

Most objects that exist in the repository ODB or that extend from object are cached and reference counted. In order to ensure we are cleaning up memory for reference counted libgit2 objects, we should always call the provided libgit2 free method on the pointers when v8 garbage collects them. A lot of these reference counted objects have an underlying memory dependency with the repository, so the repository pointer will need to be kept around until the last call to the last object related to the repository has been freed. This means that most reference counted objects are owned by the repository. This class of objects will always call the free function, even if they have an owner.

Borrowed pointers

Borrowed pointers are like fields on a struct. They should never be freed. Instead, we should build an owner dependency on the v8 object that contains the struct that this borrowed pointer came from. This ownership dependency will keep the memory alive for as long as the borrowed pointer is alive.

Borrowed, duplicable pointers

Certain borrowed pointers (git_oid, git_signature...) are easily duplicable and may have provided duplication functions from libgit2. They may also be easily copied using memcpy. If a pointer is borrowed, but duplicable, no ownership relationship should be established. Instead, we should duplicate the memory and always free when v8 garbage collects us.

Non reference counted, non duplicable, mega owners

This mostly applies to the repository. The repository has a huge network of underlying relationships between the moment you git_repository_open. Almost every reference counted object has an underlying relationship with the repository via an odb cache or just plain having a field pointing back to the repository. Most reference counted objects will form an owned relationship with the repository. Unfortunately, there are several ways to get back to the same repository pointer that you got when you performed git_repository_open. That means that we need to keep track of how many times we've seen the repository. We now have an external reference counting mechanism to keep track of pointers like the repository. As new v8 objects get created that wrap the repository pointer, we reference count. When every v8 object that wraps the repository has been garbage collected, the last one to be collected will also perform the free method on the repository.
I've currently flagged these as isSingleton and refer to them as such, but that is a silly name and I am open to suggestions (if I don't find a better name myself 😄).

Additional behavior

OwnerFn

I've added a new field to the ownerFn in the descriptor.json. An example of the ownerFn is git_commit_owner. You pass it a commit pointer and it will give you the repository pointer that it is bound to. We now utilize these functions to generate a persistent handle to the repository. When a new commit is created, we bind it to the repository via git_commit_owner. As mentioned above, we will create a new v8 object wrapper around the repository handle and reference count it. This will at least guarantee that even though it's a different v8 object wrapper that we persist, it's still persisting the important underlying libgit2 pointer.

ownedBy

You can now specify ownedBy fields in arguments to instruct the descriptor that a particular argument from JS is the owner of a return result. This extends ownedByThis behavior by being more open to other ownership configurations than a this relationship.

Need to do still

• Walk through documentation and ensure ownedBy is set on arguments at the appropriate place
• Callback memory management is still set to never free callback parameters. We will need to find out how to fish ownership details via the async payload. I am not sure if I want to complete this in this PR or push it into the future, as I imagine callbacks are a much smaller memory foot print than being able to free the repository.
• Write additional segfault tests like the ones seen in revwalk for the config, which is borderline similar to the repository, but not quite as complex.
• Write additional segfault tests in general utilizing the GC.

Future work

• Maybe callback memory managent, depends on if we can get something simple done in this PR.
• Complex owner scenarios like git_filter. It would be nice if instead of having to write a full template, we would be capable of patching the HandleOKCallback with a custom owner resolver.
• It would be nice if we also had an overwrite block specifically targeting function calls in AsyncWorker::Execute. For an example of what I am referring to, check out generate/templates/manual/clone/clone.cc.