Many coding constructs deal with the creation and deletion of various forms of data or other entities, these operations often follow certain patterns, usually there is a constructor and a destructor which must be matched one to one to insure proper program behavior. data structures may be stack allocated, heap allocated, or be part of a greater memory allocation scheme. The goal of having a consistent naming for these functions and consistent naming of matching pairs of functions is both to help with code clarity and clarity of design and thought when dealing with these types of operations.
| init/fini |
init/fini are used in two similar contexts. in both cases they initialize
pre-existing allocated memory, the only difference is where the memory comes
from. This is the only function type for which the destructor is not always
necessary to clean up all resources.
|
|---|---|
| create/destroy | These functions are used on purely abstract types which are only dealt with as pointers or some other abstract reference. it is assumed that the create allocates any memory necessary for the structure and the destroy releases any resources used by the structure including the structure itself. |
| ref/unref | These functions work upon abstract structures such as those created with create/destroy. they are used when a reference count is used as a memory management scheme. they interact with create/destroy in the following manner: ref increments a counter and unref decrements it, when it reaches zero then destroy is called. create always returns objects with a reference count of one. destroy destroys objects regardless of reference count. |
| alloc/free | when it is necessary to manage a shared resource pool with the property that any particular instance of a resource is as good as any other then these functions may be used. An example would be the C functions malloc/free, it does not matter which particular block of memory is returned by malloc, only that it is of proper size. |
| open/close | These are analogous to the similar named functions dealing with files in that they are meant for the grabbing and releasing of a handle to a specific stateful or unique resource. The idea is that open is passed a location in some sense of a resource which may be modified and exists beyond the close operation such that a subsequent open operation on the same location will return the same object. This is a deliberately vague description as this method of interaction can be applied to many programming constructs and should not be limited to files. |
The preferred usage of these roots to create function names is
object_root[_type](args...)as demonstrated in the following examples:
square_t *square_create(color_t color); void square_destroy(square_t *square); void lock_manager_init(); void mutex_init(mutex_t *m); void mutex_fini(mutex_t *m); stream_t *stream_create_fd(int fd); stream_t *stream_create_string(char *string);