This blogpost (as part of the
H2O Advent Calendar 2014) provides a high-level overview of the memory management functions in H2O that can be categorized into four groups.
h2o_mem_alloc, h2o_mem_realloc
They are wrappers of
malloc(3) /
realloc(3), that calls
abort(3) if memory allocation fails. The returned chunks should be freed by calling
free(3).
h2o_mem_init_pool, h2o_mem_clear_pool, h2o_mem_alloc_pool
The functions create, clear, and allocate from a
memory pool. The term
memory pool has several meanings, but in case of H2O the term has been borrowed from
Apache; it refers to a memory allocator that frees all associated chunks at once when the destructor (
h2o_mem_clear_pool) is being called.
The primary use-case of the functions is to allocate memory that relates to a HTTP request. The request object
h2o_req_t has a memory pool associated to it; small chunks of memory that need to be allocated while handling a request should be obtained by calling
h2o_mem_alloc_pool instead of
h2o_mem_alloc, since the former is generally faster than the latter.
h2o_mem_alloc_shared, h2o_mem_link_shared, h2o_mem_addref_shared, h2o_mem_release_shared
They are the functions to handle ref-counted chunks of memory. Eeach shared chunk has its own
dispose callback that gets called when the reference counter reaches zero. A chunk can be optionally associated to a memory pool, so that the reference counter gets decremented when the pool gets flushed.
The functions are used for handling things like headers transferred via HTTP/2, or to for associating a resource that needs a custom dispose callback to a HTTP request through the use of the memory pool.
h2o_buffer_init, h2o_buffer_dispose, h2o_buffer_reserve, h2o_buffer_consume, h2o_buffer_link_to_pool
The functions provide access to
buffer, that can hold any length of octets. They internally use
malloc(3) /
realloc(3) for handling short buffers, and switch to using temporary-file-backed
mmap(2) when the length of the buffer reaches a predefined threshold (default: 32MB). A buffer can also be associated to memory pool by calling the
h2o_buffer_link_to_pool function.
The primary use-case of the buffer is to store incoming HTTP requests and POST contents (as it can be used to hold huge chunks on 64-bit systems since it switches to temporary-file-backed memory as described).
h2o_vector_reserve
The function reserves given number of slots for
H2O_VECTOR which is a variable length array of an arbitrary type of data. Either
h2o_mem_realloc or the memory pool can be used as the underlying memory allocator (in the former case, the allocated memory should be manually freed by the caller). The structure is initialized by zero-filling it.
The vector is used everywhere, from storing a list of HTTP headers to a list of configuration directives.
For details, please refer to their doc-comment and the definitions in
include/h2o/memory.h and
lib/memory.c.
