Garbage collector

---

Detailed Description

In brief: this module adds a feature to delay the destruction of pointers of different sizes, thus allowing the application to reuse some pointers not really deleted yet. See the mem_pool module for another type of allocation optimization feature.

A simple garbage collector (with explicit collection) which provides asynchronous deletion. It is probably only useful when an application could avoid to recreate the same objects, when all objects are not of the same size. If it's better for you to just keep them a few seconds or minutes before really delete them, in case you want to reuse them, so this module is probably for you. When it's time to really delete an object, the library calls your callback: if the object has been reused since, just ignore the call... or really delete it otherwise.

This module has been created in order to optimize allocations of IRC channels, which are allocated structures of different sizes (different names) and commonly deleted and re-allocated just after (part/join of an empty channel). I am not sure it will suit for something else.

Usage is very easy: initialize a garbage collector object with peak_garbage_create() providing a generic deletion callback for all collected objects, then call peak_garbage_collect() for each object you want to delete using the collector. The objects will be automatically deleted (you shouldn't predict the deletion, as the frequency is only a hint - note it's usually less because all collected objects are always deleted at the same time). If needed, you can force all objects deletion with the peak_garbage_vacuum() function.

Typedefs
typedef __peak_garbage *	peak_garbage
	Opaque garbage collector pointer type.
typedef void(*	peak_garbage_callback )(peak_garbage g, void *ptr, void *context)
	Deletion's callback definition.
Functions
peak_garbage	peak_garbage_create (int max_ptrs, double frequency, peak_task task, peak_garbage_callback callout, void *context)
	Create a garbage object.
void	peak_garbage_collect (peak_garbage g, void *ptr)
	Collect a pointer and schedules the garbage's task for deletion.
int	peak_garbage_get_collected_count (peak_garbage g)
	Get the current number of pointers collected for deletion.
void	peak_garbage_vacuum (peak_garbage g)
	Perform manual vacuuming.

---

Function Documentation

void peak_garbage_collect (  peak_garbage  g, void *  ptr )

Collect a pointer and schedules the garbage's task for deletion. Guaranteed O(1) unless max_ptrs is reached. Parameters: g  The garbage object reference. ptr  Pointer to collect for deletion.

peak_garbage peak_garbage_create (  int  max_ptrs, double  frequency, peak_task  task, peak_garbage_callback  callout, void *  context )

Create a garbage object. Parameters: max_ptrs  Max pointers that the garbage object can collect at the same time. Must be strictly positive. If reached, a vacuuming is performed and the object properly collected. frequency  Frequency hint in seconds at which you want to do the vacuuming (deletions), it's usually less because when vacuuming the callback is called for all objects already collected. task  Task to schedule, can be NULL to use current task. callout  A pointer to your deletion callback function which is triggered when automatic of manual vacuuming. context  An extra application-defined pointer that will be passed to your garbage callback function. Returns: A newly allocated peak_garbage reference or NULL if the object cannot be created.

int peak_garbage_get_collected_count (  peak_garbage  g  )

Get the current number of pointers collected for deletion. Parameters: g  The garbage object reference. Returns: Collected pointers count.

void peak_garbage_vacuum (  peak_garbage  g  )

Perform manual vacuuming. Parameters: g  The garbage object reference.

---