lzma_allocator Struct Reference

Custom functions for memory handling. More...

#include <base.h>

Data Fields
void *(*	alloc )(void *opaque, size_t nmemb, size_t size)
	Pointer to a custom memory allocation function.
void(*	free )(void *opaque, void *ptr)
	Pointer to a custom memory freeing function.
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(). C++ users should note that the custom memory handling functions must not throw exceptions.

Single-threaded mode only: 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).

Multithreaded mode: liblzma might internally store pointers to the lzma_allocator given via the lzma_stream structure. The application must not change the allocator pointer in lzma_stream or the contents of the pointed lzma_allocator structure until lzma_end() has been used to free the memory associated with that lzma_stream. The allocation functions might be called simultaneously from multiple threads, and thus they must be thread safe.

Field Documentation

alloc

void *(* 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.

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.

free

void(* lzma_allocator::free) (void *opaque, void *ptr)

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().

opaque

void* lzma_allocator::opaque

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.

---

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

• lzma/base.h