Nix 2.28.2
Nix, the purely functional package manager: C API (experimental)
 
Loading...
Searching...
No Matches

Reference counting and garbage collector operations. More...

Functions

nix_err nix_gc_incref (nix_c_context *context, const void *object)
 Increment the garbage collector reference counter for the given object.
 
nix_err nix_gc_decref (nix_c_context *context, const void *object)
 Decrement the garbage collector reference counter for the given object.
 
void nix_gc_now ()
 Trigger the garbage collector manually.
 
void nix_gc_register_finalizer (void *obj, void *cd, void(*finalizer)(void *obj, void *cd))
 Register a callback that gets called when the object is garbage collected.
 

Detailed Description

Reference counting and garbage collector operations.

The Nix language evaluator uses a garbage collector. To ease C interop, we implement a reference counting scheme, where objects will be deallocated when there are no references from the Nix side, and the reference count kept by the C API reaches 0.

Functions returning a garbage-collected object will automatically increase the refcount for you. You should make sure to call nix_gc_decref when you're done with a value returned by the evaluator.

Function Documentation

◆ nix_gc_decref()

nix_err nix_gc_decref ( nix_c_context * context,
const void * object )

Decrement the garbage collector reference counter for the given object.

Parameters
[out]contextOptional, stores error information
[in]objectThe object to stop referencing

◆ nix_gc_incref()

nix_err nix_gc_incref ( nix_c_context * context,
const void * object )

Increment the garbage collector reference counter for the given object.

The Nix language evaluator C API keeps track of alive objects by reference counting. When you're done with a refcounted pointer, call nix_gc_decref().

Parameters
[out]contextOptional, stores error information
[in]objectThe object to keep alive

◆ nix_gc_now()

void nix_gc_now ( )

Trigger the garbage collector manually.

You should not need to do this, but it can be useful for debugging.

◆ nix_gc_register_finalizer()

void nix_gc_register_finalizer ( void * obj,
void * cd,
void(* finalizer )(void *obj, void *cd) )

Register a callback that gets called when the object is garbage collected.

Note
Objects can only have a single finalizer. This function overwrites existing values silently.
Parameters
[in]objthe object to watch
[in]cdthe data to pass to the finalizer
[in]finalizerthe callback function, called with obj and cd