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. More...

	void (LZMA_API_CALL free)(void opaque
	Pointer to a custom memory freeing function. More...

Public Attributes
void *	ptr

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

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.

Definition at line 372 of file base.h.

Member Function Documentation

◆ alloc()

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.

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.

Referenced by lzma_attribute().

◆ void()

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

Member Data Documentation

◆ 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.

Definition at line 432 of file base.h.

Referenced by lzma_attribute(), and lzma_free().

◆ ptr

void* lzma_allocator::ptr

Definition at line 421 of file base.h.

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

subprojects/xz-5.2.5/src/liblzma/api/lzma/base.h

Public Member Functions