prg_list_destroy()
Abstract
Destroys a list, including the list infrastructure, and optionally the items in the list
Syntax
prg_list_destroy (list_ptr, dealloc_elements)
| Argument | Type | Description |
|---|---|---|
list_ptr |
PrgT_List * |
list to be destroyed |
dealloc_elements |
int |
treat as a boolean; elements will be deallocated if TRUE, otherwise, they will remain untouched by the call. |
Return Type
void
no return value
Header
prg_list_funcs.h
Details
This is an alternative to using prg_list_free() to destroy a list. prg_list_free() always deallocates the elements in the list, and does not destroy the list container. In other words, prg_list_free() empties out the list and deallocates all the elements (by calling an appropriate memory deallocator, if possible), but the empty list is still viable afterwards as a container. If you wish to destroy the container, you must then call prg_mem_free() on the list pointer.
In contrast, prg_list_destroy() leaves no viable list in place and, in addition, allows you to control whether or not the list's elements will be deallocated. In other words, you can use prg_list_destroy() to eliminate a list in one call and, if you choose, also deallocate the elements in the list. If the elements are pointers to data that you wish to keep after the destruction completes (that is, the list is merely a “view” or an “arrangement” of those data elements), then specify that deallocation of elements should not be performed.
WARNING: This function is MT unsafe, as described in “Multi-Threading Safety“ on page 11. Access to shared lists must be externally serialized.