Smartish pointers

Non-automatic smart pointers. More...

Modules
	Guarded pointers
	Object to guard against direct copying of pointers.
	Unique Pointers
	Dynamically-allocated memory with a single owner.
	Shared Pointers
	Reference-counted, dynamically-allocated memory.
	Weak Pointers
	Non-"owning" reference to a shared pointer.

Detailed Description

Non-automatic smart pointers.

In C++, memory can be allocated using unique_ptrs and shared_ptrs, and the memory associated with them is freed automatically when they go out of scope. The objects here attempt to mimic that behavior, but in C, the caller is responsible for managing the lifetime of the objects. The improvement here is that the caller must reset the object(s) whenever they go out of scope.

For example, without a smart pointer, the code may look something like:

{
    void * data = malloc(len);
 
    (void)somefunc(data);
 
    // uh-oh, did somefunc() keep a pointer to data?
    // who is supposed to free it? this function
    // or somefunc()?
}

With a smart pointer, the above would look like:

{
    DECLARE_CSTL_UNIQUE_PTR(data);
    cstl_unique_ptr_alloc(&data, len, NULL);
 
    (void)somefunc(&data);
 
    // it doesn't matter whether somefunc() kept
    // the pointer or not. this code must reset
    // the object before it goes out of scope.
 
    cstl_unique_ptr_reset(&data);
}