cru_destructor - memory reclamation function used by the cru library
#include <cru/cru.h>
typedef void (*cru_destructor)(void *, int *)
A user-defined function matching this prototype is passed a non- NULL pointer to a disused vertex, edge label, or property of some application-specific form, and a pointer to an integer error code initialized to zero. The function is expected to reclaim all storage addressed by the pointer appropriately for the application, whether contiguous or otherwise.
If a destructor function sets the error code to any non-zero value, the cru API function that called it terminates early and propagates the same error code to its caller. In the interest of orderly termination, further calls to the same destructor may be made regardless, with the error code re-initialzed to zero on entry.
Applications can report POSIX error codes or define special purpose codes, but should not redefine any that clash with those reserved by cru as declared in the error_codes.h header file.
Applications pass destructors to cru API functions via pointers to them in any of these four fields:
The first two are for reclaiming vertices and edge labels, respectively, of a graph built with that cru_destructor_pair structure in the bu_sig field of its cru_builder. The r_free field is for results returned by functions specified by the reduction and the vacuous_case fields in the same cru_fold and the m_free field is for those of the map field in it.
If any of the destructor fields is NULL, cru infers that the corresponding vertex, edge, or function result is a scalar value in no need of reclamation, and may also infer default hash functions and relations for it.
Applications ordinarily allocate separate storage locations for every vertex, edge, or function result. In this case case, no locking of the arguments is required of the destructors.
Some applications may opt to trade performance for space efficiency by using shared storage, typically with some form of reference counting. This approach is also valid, but requires additional care. Destructors in this case must ensure thread-safe mutually exclusive access to any shared storage using pthreads primitives or alternatives.
Missing or deficient destructors can cause memory leaks. Their correctness is not enforceable.
If the vertices in a graph are large enough to make shared copies worthwhile,
typedef struct
{
uintptr_t reference_count;
unsigned very_large_contents[0x10000];
} *my_vertex_type;then a simple reference counting destructor can be safely implemented as shown
static pthread_mutex_t global_lock = PTHREAD_MUTEX_INITIALIZER;
void
my_vertex_destructor (my_vertex_type v, int *err)
{
pthread_mutex_lock (&global_lock);
if (! (v->reference_count)--)
free (v);
pthread_mutex_unlock (&global_lock);
}under the assumption of vertices allocated with initial reference counts of zero to be incremented once for each shared copy.
/usr/local/include/cru/function_types.h
/usr/local/include/cru/data_types.h
/usr/local/include/cru/error_codes.h
cru, cru_bop, cru_bpred, cru_builder, cru_built, cru_cbop, cru_classifier, cru_class_of, cru_class_size, cru_composed, cru_composer, cru_connect, cru_connector, cru_cqop, cru_crossed, cru_crosser, cru_ctop, cru_ctop_pair, cru_ctop_quad, cru_data_types, cru_deduplicated, cru_destructor_pair, cru_edge_count, cru_fabricated, cru_fabricator, cru_filter, cru_filtered, cru_fold, cru_free_kill_switch, cru_free_later, cru_free_now, cru_free_partition, cru_function_types, cru_get, cru_hash, cru_induced, cru_inducer, cru_kernel, cru_kill, cru_killed, cru_mapreduced, cru_mapreducer, cru_merged, cru_merger, cru_mutated, cru_mutator, cru_new_kill_switch, cru_nop, cru_order, cru_order_pair, cru_partition_of, cru_plan, cru_postponed, cru_postponer, cru_prop, cru_prop_pair, cru_pruner, cru_qop, cru_qpred, cru_set, cru_sig, cru_singleton, cru_split, cru_splitter, cru_spread, cru_strerror, cru_stretch, cru_stretched, cru_stretcher, cru_subconnector, cru_terminus_count, cru_top, cru_tpred, cru_united, cru_uop, cru_vertex_count, cru_zone
Dennis Furey (milonga@delayinsensitive.com)
https://github.com/gueststar/cru