|
StdGUI Memory Functions |
|
char *strclone(const char *p_str); void *memclone(const void *p_ptr, size_t p_size); void auto_release(void); int reserve_ptr(void *p_ptr); int release_ptr(void *p_ptr); int acquire_ptr(void *p_ptr, size_t *p_len); int contrib_ptr(void *p_ptr, size_t p_len); |
|
The strclone() function allocates enough space for a copy of the string parameter and copies the string into the newly allocated memory block, returning the new string. The memclone() function is similar to the strclone() function except that it works on arbitrary blocks of memory (not just C-strings) and takes a size parameter indicating the size of the memory block to copy. The auto_release() function releases any memory allocated by the library in the auto-release pool. Auto-release pool memory is used to return dynamically allocated strings or structures from a number of StdGUI routines (specifically, get_window_info() returns the p_title parameter as an auto-release object, get_property() and get_ind_property() return the p_value parameter as an auto-release object, index_property() returns the .p_name parameter as an auto-release object and index_user_data() returns the p_name parameter as an auto-release object). These returned values may be treated as if they were statically allocated, so long as they are only referenced within the current callback invocation (and before an explicit call to auto_release()). If you need to make long term use of an auto-release object, you can either make a clone of the object (using strclone() or memclone() or get temporary or permanent ownership of the object (using reserve_ptr() or acquire_ptr()). The reserve_ptr() function tells the auto-release pool that a pointer is in long-term use by the client code, and prevents calls to auto_release() from releasing the memory. The release_ptr() function allows previously reserved memory to be released by the auto-release pool. The reserve and release functions implement a primitive sort of reference counting, so you will need to call release_ptr() at least as many times as you previously called reserve_ptr() before the auto-release pool will be able to reclaim the memory. The acquire_ptr() function wrests complete control of a pointer from the auto-pool system. Once you have acquired a pointer, it is up to you to dispose of it properly. Memory acquired from the auto-release system can be disposed of simply by calling the standard C library free() function. The contrib_ptr() function submits a pointer to the auto-pool system for it to manage. The pointer may be either one that was previously acquired from the auto-pool or any pointer allocated by the standard C malloc() function. Once a pointer has been contributed to the auto-release pool it is unsafe to use, as it may be reused at any time: treat such a pointer as if it had been disposed of by a call to free(). |
|
The strclone() and memclone() functions return a valid memory pointer on success, NULL on failure. The auto_release() function has no return value. The reserve_ptr(), release_ptr(), acquire_ptr() and contrib_ptr() functions all return zero (0) on success, non-zero on failure. |
|
Jeffrey Dutky |