Module rspamd_mempool

Rspamd memory pool is used to allocate memory attached to specific objects, namely it was initially used for memory allocation for rspamd_task.

All memory allocated by the pool is destroyed when the associated object is destroyed. This allows a sort of controlled garbage collection for memory allocated from the pool. Memory pools are extensively used by rspamd internal components and provide some powerful features, such as destructors or persistent variables.

Example:

local mempool = require "rspamd_mempool"
local pool = mempool.create()

pool:set_variable('a', 'bcd', 1, 1.01, false)
local v1, v2, v3, v4 = pool:get_variable('a', 'string,double,double,bool')
pool:destroy()

Brief content:

Functions:

mempool.create([size]): function.

Methods:

mempool:add_destructor(func): method.

mempool:destroy(): method.

mempool:set_variable(name, [value1[, value2 ...]]): Sets a variable that’s valid during memory pool lifetime.

mempool:set_bucket(name, num_values, [value1...valuen]|[table]): Stores a variable bucket of numbers where the first number is number of elements to pack.

mempool:get_variable(name[, type]): Unpacks mempool variable to lua If type is not specified, then a variable is.

mempool:has_variable(name): method.

mempool:delete_variable(name): method.

Functions

The module rspamd_mempool defines the following functions.

Function mempool.create([size])

Creates a memory pool of a specified size or platform dependent optimal size (normally, a page size)

Parameters:

  • size {number}: size of a page inside pool

Returns:

  • {rspamd_mempool}: new pool object (that should be removed by explicit call to pool:destroy())

Back to module description.

Methods

The module rspamd_mempool defines the following methods.

Method mempool:add_destructor(func)

Adds new destructor function to the pool

Parameters:

  • func {function}: function to be called when the pool is destroyed

Returns:

No return

Back to module description.

Method mempool:destroy()

Destroys memory pool cleaning all variables and calling all destructors registered (both C and Lua ones)

Parameters:

No parameters

Returns:

No return

Back to module description.

Method mempool:set_variable(name, [value1[, value2 ...]])

Sets a variable that’s valid during memory pool lifetime. This function allows to pack multiple values inside a single variable. Currently supported types are:

  • string: packed as null terminated C string (so no \0 are allowed)
  • number: packed as C double
  • boolean: packed as bool

Parameters:

  • name {string}: variable’s name to set

Returns:

No return

Back to module description.

Method mempool:set_bucket(name, num_values, [value1...valuen]|[table])

Stores a variable bucket of numbers where the first number is number of elements to pack and then there should be either n numeric values or a plain table of numeric values

Parameters:

  • name {string}: variable’s name to set
  • num_values {number}: number of variables in the bucket
  • values {table|list}: values

Returns:

No return

Back to module description.

Method mempool:get_variable(name[, type])

Unpacks mempool variable to lua If type is not specified, then a variable is assumed to be zero-terminated C string. Otherwise, type is a comma separated (spaces are ignored) list of types that should be unpacked from a variable’s content. The following types are supported:

  • string: null terminated C string (so no \0 are allowed)
  • double: returned as lua number
  • int: unpack a single integer
  • int64: unpack 64-bits integer
  • boolean: unpack boolean
  • bucket: bucket of numbers represented as a Lua table
  • fstrings: list of rspamd_fstring_t (GList) represented as a Lua table

Parameters:

  • name {string}: variable’s name to get
  • type {string}: list of types to be extracted

Returns:

  • {variable list}: list of variables extracted (but not a table)

Back to module description.

Method mempool:has_variable(name)

Checks if the specified variable name exists in the memory pool

Parameters:

  • name {string}: variable’s name to get

Returns:

  • {boolean}: true if variable exists and false otherwise

Back to module description.

Method mempool:delete_variable(name)

Removes the specified variable name from the memory pool

Parameters:

  • name {string}: variable’s name to remove

Returns:

  • {boolean}: true if variable exists and has been removed

Back to module description.

Back to top.