This section defines an interface for handling reference-counted binary buffers. The cork_managed_buffer type wraps a buffer with a simple reference count, and takes care of freeing the necessary resources when the reference count drops to zero. There should only be a single cork_managed_buffer instance for any given buffer, regardless of how many threads or functions access that buffer. Each thread or function that uses the buffer does so via a cork_slice instance. This type is meant to be allocated directly on the stack (or in some other managed storage), and keeps a pointer to the managed buffer instance that it slices. As its name implies, a slice can refer to a subset of the buffer.
A “managed buffer”, which wraps a buffer with a simple reference count.
Managed buffer consumers should consider all of the fields of this class private. Managed buffer implementors should fill in this fields when constructing a new cork_managed_buffer instance.
The buffer that this instance manages.
The size of buf.
A reference count for the buffer. If this drops to 0, the buffer will be finalized.
Atomically increase the reference count of a managed buffer. This function is thread-safe.
Atomically decrease the reference count of a managed buffer. If the reference count falls to 0, the instance is freed. This function is thread-safe.
Initialize a new slice that refers to a subset of a managed buffer. The offset and length parameters identify the subset. (For the _slice_offset variant, the length is calculated automatically to include all of the managed buffer content starting from offset.) If these parameters don’t refer to a valid portion of the buffer, we return false, and you must not try to deference the slice’s buf pointer. If the slice is valid, we return true.
Regardless of whether the new slice is valid, you must ensure that you call cork_slice_finish() when you are done with the slice.
Make a copy of buf, and allocate a new managed buffer to manage this copy. The copy will automatically be freed when the managed buffer’s reference count drops to 0.
A finalization function for a managed buffer created by cork_managed_buffer_new().
Allocate a new managed buffer to manage an existing buffer (buf). The existing buffer is not copied; the new managed buffer instance takes control of it. When the managed buffer’s reference count drops to 0, it will call free to finalize buf.
This is a helper function, and keeps you from having to write a complete custom managed buffer implementation when you don’t need to store any additional state in the managed buffer object.
The free function is not responsible for freeing the cork_managed_buffer instance itself.