The next five calls implement a layer on top of standard memory allocation. They allow to allocate special block arenas from which memory is allocated. All blocks in a block arena have the same size that was specified when the arena was created. The MEM module uses a paging algorithm to allocate and release blocks very efficiently without searching lists and without adding block headers. The bookkeeping overhead is
sizeof(char*) bytes for every 8192 allocated block bytes, assuming that the block size is a multiple of
sizeof(char*). All memory allocated by block arena calls will appear with the caller's module number in
mi_mem_dump and
mi_mem_summary listings.
- miMemblk *mi_mem_int_blkcreate (int size)
- Create a block arena. All blocks allocated from this arena will have a size of size bytes, rounded up to the next sizeof(char*)-byte boundary. The minimum size is sizeof(char*), the maximum is currently 8192. The returned arena identifier must be used in all other block arena calls to identify the arena. There is no limit on the number of arenas and on the number of blocks in an arena. The returned arena structure will show up with the caller's file and line information in mi_mem_dump and mi_mem_summary listings.
- void mi_mem_blkdelete (miMemblk * const arena)
- Delete an arena and all its blocks. The blocks allocated from this arena become invalid. The arena handle may no longer be used.
- void *mi_mem_blkallocate (miMemblk * const arena)
- Allocate a block from arena. The size of the block is determined by the size argument given to the mi_mem_int_blkcreate call that created arena. The returned block is zeroed. This call is very fast, except on the first allocation from a new arena, and whenever an 8 KB page fills up. The pages show up with the file name memblock.c in mi_mem_dump and mi_mem_summary listings.
- void *mi_mem_blkfallocate (miMemblk * const arena)
- This call is equivalent to mi_mem_blkallocate, but it performs no locking and doesn't guard against the network thread. It is considerably faster (the ``f'' stands for fast), but may be used only if two conditions are met: the arena may not be shared between multiple threads, (i.e. arena is a thread-local variable that is not used in other threads), and it must never be called from the network thread. If the program is compiled with DEBUG, it will abort if a call from the network thread is attempted.
- void mi_mem_blkrelease (miMemblk * const arena,
- void * const block) Release the block block. block must be a pointer obtained from a call to mi_mem_blkallocate from the same arena. No check is done to verify that block is released to the correct arena. The next block allocation will probably return the last block released. The memory pointed to by block may no longer be used.
- void mi_mem_blkclear (miMemblk * const arena)
- Release all memory blocks allocated from arena. This call is more efficient than calling mi_mem_blkrelease for every allocated block. The implementation retains the allocated memory pages, blocks are merely marked invalid and are re-used when new blocks are allocated from the cleared arena.
- void mi_mem_blkenumerate (miMemblk * const arena,
- void (*callback)(void *)) Call the callback for every currently allocated block in the arena, with the pointer to the allocated block as it had been returned by mi_mem_blkallocate or mi_mem_blkfallocate. Blocks that have been deleted with mi_mem_blkrelease are not considered ``currently allocated''. The order of the callbacks is undefined and does not necessarily conform to the allocation order. The arena may not be modified while the enumeration is in progress; neither the callback nor another thread may modify it before mi_mem_blkenumerate returns.