lzma_allocator Struct Reference

Custom functions for memory handling. More...

#include <base.h>


Public Member Functions

void *LZMA_API_CALL * alloc (void *opaque, size_t nmemb, size_t size)
 Pointer to a custom memory allocation function.
 void (LZMA_API_CALL *free)(void *opaque
 Pointer to a custom memory freeing function.

Data Fields

void * ptr
void * opaque
 Pointer passed to .alloc() and .free().


Detailed Description

Custom functions for memory handling.

A pointer to lzma_allocator may be passed via lzma_stream structure to liblzma, and some advanced functions take a pointer to lzma_allocator as a separate function argument. The library will use the functions specified in lzma_allocator for memory handling instead of the default malloc() and free().

liblzma doesn't make an internal copy of lzma_allocator. Thus, it is OK to change these function pointers in the middle of the coding process, but obviously it must be done carefully to make sure that the replacement `free' can deallocate memory allocated by the earlier `alloc' function(s).


Member Function Documentation

void* LZMA_API_CALL* lzma_allocator::alloc ( void *  opaque,
size_t  nmemb,
size_t  size 
)

Pointer to a custom memory allocation function.

If you don't want a custom allocator, but still want custom free(), set this to NULL and liblzma will use the standard malloc().

Parameters:
opaque lzma_allocator.opaque (see below)
nmemb Number of elements like in calloc(). liblzma will always set nmemb to 1, so it is safe to ignore nmemb in a custom allocator if you like. The nmemb argument exists only for compatibility with zlib and libbzip2.
size Size of an element in bytes. liblzma never sets this to zero.
Returns:
Pointer to the beginning of a memory block of `size' bytes, or NULL if allocation fails for some reason. When allocation fails, functions of liblzma return LZMA_MEM_ERROR.
For performance reasons, the allocator should not waste time zeroing the allocated buffers. This is not only about speed, but also memory usage, since the operating system kernel doesn't necessarily allocate the requested memory in physical memory until it is actually used. With small input files liblzma may actually need only a fraction of the memory that it requested for allocation.

Note:
LZMA_MEM_ERROR is also used when the size of the allocation would be greater than SIZE_MAX. Thus, don't assume that the custom allocator must have returned NULL if some function from liblzma returns LZMA_MEM_ERROR.

lzma_allocator::void ( LZMA_API_CALL *  free  ) 

Pointer to a custom memory freeing function.

If you don't want a custom freeing function, but still want a custom allocator, set this to NULL and liblzma will use the standard free().

Parameters:
opaque lzma_allocator.opaque (see below)
ptr Pointer returned by lzma_allocator.alloc(), or when it is set to NULL, a pointer returned by the standard malloc().


Field Documentation

Pointer passed to .alloc() and .free().

opaque is passed as the first argument to lzma_allocator.alloc() and lzma_allocator.free(). This intended to ease implementing custom memory allocation functions for use with liblzma.

If you don't need this, you should set this to NULL.

Referenced by lzma_free().


The documentation for this struct was generated from the following file:

Generated on Wed May 25 10:35:47 2011 for XZ Utils by  doxygen 1.5.5