From 002caadb8140b6ced9cc14228612be8dd68b6618 Mon Sep 17 00:00:00 2001 From: Jeremy Tregunna Date: Mon, 25 Apr 2016 20:36:23 -0600 Subject: [PATCH] add some commentary --- refuse.h | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/refuse.h b/refuse.h index 42ec902..b49ae15 100644 --- a/refuse.h +++ b/refuse.h @@ -18,12 +18,44 @@ typedef struct refdeque_t* mod; } refuse_t; +// Create a new garbage collector. It should be noted, that refuse is +// not yet thread safe. Therefore it's recommended that refuse run in +// its own thread. Objects may be shared across thread boundaries for +// the purposes of your use case, however, all operations, save for +// refuse_alloc, must be run on the thread that owns refuse. extern refuse_t* refuse_new(void); + +// Allocate a chunk of memory and place it under control of an instance +// of refuse. The pointer returned points at the start of memory for +// your object, and you do not need to supply any header yourself. extern void* refuse_alloc(refuse_t*, size_t); + +// Destroy the garbage collector. This will run the reconciler, and +// deallocate all internal state. It is not safe to use your refuse +// instance after calling this function. extern void refuse_destroy(refuse_t*); + +// Mark an object as dirty. This has the benefit of avoiding a retain +// call for each modification to the parameter you do, until the +// reconciler runs. At that point, the dirty bit will be reset. extern void refuse_set_dirty(refuse_t*, void*); + +// Reconcile the retains and releases. This must be done at periodic +// intervals, i.e., when returning from a function, or somesuch. It +// should be done often enough that you never have too many items +// queued up, but not too often as to negate the risk of the +// optimizations this library provides on top of reference counting. +// +// Measure twice. extern void refuse_reconcile(refuse_t*); + +// Mark an object for retain. It will not be retained immediately, +// but you are guaranteed to retain the object before any release will +// be applied against it. extern void refuse_retain(refuse_t*, void*); + +// Mark an object for release. This object will not be released +// immediately, but at some indeterminate point in the future. extern void refuse_release(refuse_t*, void*); #ifdef __cplusplus