4. Package for work with stacks of objects

The package `objstack' is based on package `allocate' and implements efficient work with stacks of objects (OS). Work with the object on the stack top is analogous to one with a variable length object. One motivation for the package is the problem of growing char strings in symbol tables. Memory for OS is allocated by segments. A segment may contain more one objects. The most recently allocated segment contains object on the top of OS. If there is not sufficient free memory for the top object than new segment is created and the top object is transferred into the new segment, i.e. there is not any memory reallocation. Therefore the top object may change its address. But other objects never change address.

The package uses package `allocate'. The interface part of the package is file `objstack.h'. Defining macro `NDEBUG' (e.g. by option `-D' in C++ compiler command line) before inclusion of the interface file disables fixing some internal errors and errors of usage of the package. The implementation part is file `objstack.cpp'. The interface contains the following objects:

Type `os_t'

describes a descriptor of stack of objects. The type is simply synonym of `class os'. All work with stack of objects is executed through the descriptors. It should remember that work with the stack through several descriptors is not safe.

Macro `OS_DEFAULT_SEGMENT_LENGTH'

has value which is default size of memory segments which will be allocated for OS when the stack is created (with not given initial segment size). This is also minimal size of all segments. Original value of the macros is equal to 512. This macro can be redefined in C++ compiler command line or with the aid of directive `#undef' before including the interface file.

Class `os'

The class contains the following functions:

Public constructor `os'

           `os (size_t initial_segment_length
                            = OS_DEFAULT_SEGMENT_LENGTH)'
           

creates OS which contains the single zero length object. Minimum size of memory segments which will be allocated for OS is given as the parameter. If the parameter is absent the allocated memory segments length is equal to `OS_DEFAULT_SEGMENT_LENGTH'. But in any case the segment length is always not less than maximum alignment.

Public destructor ` os'

           `~os (void)'
           

is used for deleting the descritor of OS and freeing memory used by the OS.

Public function `empty'

           `void empty (void)'
           

is used for removing all objects on OS and freeing all memory allocated for OS except for the first segment.

Public function `top_finish'

           `void top_finish (void)'
           

creates new variable length object with initial zero length on the top of OS of given descriptor. The work (analogous to one with variable length object) with object which was on the top of OS is finished, i.e. the object will never more change address.

Public function `top_nullify'

           `void top_nullify (void)'
           

makes that length of variable length object on the top of OS of given descriptor will be equal to zero.

Public function `top_length'

           `size_t top_length (os)'
           

returns current length of variable length object on the top of OS of given descriptor.

Public functions `top_begin', `top_end', `top_bound'

           `void *top_begin (void)', `void *top_end (void)',
           `void *top_bound (void)'
           

return pointer to correspondingly the first, the last byte of variable length object on the top of OS of given descriptor, and pointer to the last byte plus one. Remember that the top object may change own place after any addition.

Public function `top_shorten'

           `void top_shorten (size_t n)'
           

removes n bytes from the end of variable length object on the top of OS of given descriptor. The top variable length object is nullified if its length is less than n.

Public function `top_expand'

           `void top_expand (size_t length)'
           

increases length of variable length object on the top of OS of given descriptor on number of bytes given as the parameter. The values of bytes added to the end of variable length object on the top of OS will be not defined.

Public function `top_add_byte'

           `void top_add_byte (int b)'
           

adds byte given as the parameter to the end of variable length object on the top of OS of given descriptor.

Public function `top_add_memory'

           `void top_add_memory (void *str, size_t length)'
           

adds memory starting with address given as the first parameter and with length given as the second parameter to the end of variable length object on the top of OS of given descriptor.

Public function `top_add_string'

           `void top_add_string (const char *str)'
           

adds C++ string (with end marker 0) given as the parameter to the end of variable length string on the top of OS of the descriptor. Before the addition the macro deletes last character of the top variable length object. The last character is suggested to be C++ string end marker 0.