View Source Nebulex.Adapters.Local.Generation (Nebulex v2.6.2)

Generational garbage collection process.

The generational garbage collector manage the heap as several sub-heaps, known as generations, based on age of the objects. An object is allocated in the youngest generation, sometimes called the nursery, and is promoted to an older generation if its lifetime exceeds the threshold of its current generation (defined by option :gc_interval). Every time the GC runs (triggered by :gc_interval timeout), a new cache generation is created and the oldest one is deleted.

The deletion of the oldest generation happens in two steps. First, the underlying ets table is flushed to release space and only marked for deletion as there may still be processes referencing it. The actual deletion of the ets table happens at next GC run.

However, flushing is a blocking operation, once started, processes wanting to access the table will need to wait until it finishes. To circumvent this, flushing can be delayed by configuring :gc_flush_delay to allow time for these processes to finish their work without being accidentally blocked.

The only way to create new generations is through this module (this server is the metadata owner) calling new/2 function. When a Cache is created, a generational garbage collector is attached to it automatically, therefore, this server MUST NOT be started directly.

Options

These options are configured through the Nebulex.Adapters.Local adapter:

  • :gc_interval - If it is set, an integer > 0 is expected defining the interval time in milliseconds to garbage collection to run, delete the oldest generation and create a new one. If this option is not set, garbage collection is never executed, so new generations must be created explicitly, e.g.: MyCache.new_generation(opts).

  • :max_size - If it is set, an integer > 0 is expected defining the max number of cached entries (cache limit). If it is not set (nil), the check to release memory is not performed (the default).

  • :allocated_memory - If it is set, an integer > 0 is expected defining the max size in bytes allocated for a cache generation. When this option is set and the configured value is reached, a new cache generation is created so the oldest is deleted and force releasing memory space. If it is not set (nil), the cleanup check to release memory is not performed (the default).

  • :gc_cleanup_min_timeout - An integer > 0 defining the min timeout in milliseconds for triggering the next cleanup and memory check. This will be the timeout to use when either the max size or max allocated memory is reached. Defaults to 10_000 (10 seconds).

  • :gc_cleanup_max_timeout - An integer > 0 defining the max timeout in milliseconds for triggering the next cleanup and memory check. This is the timeout used when the cache starts and there are few entries or the consumed memory is near to 0. Defaults to 600_000 (10 minutes).

  • :gc_flush_delay - If it is set, an integer > 0 is expected defining the delay in milliseconds before objects from the oldest generation are flushed. Defaults to 10_000 (10 seconds).

Summary

Functions

Returns a specification to start this module under a supervisor.

Removes or flushes all entries from the cache (including all its generations).

A convenience function for retrieving the state.

Returns the list of the generations in the form [newer, older].

Returns the memory info in a tuple form {used_mem, total_mem}.

Creates a new cache generation. Once the max number of generations is reached, when a new generation is created, the oldest one is deleted.

Returns the newer generation.

Reallocates the block of memory that was previously allocated for the given server_ref with the new size. In other words, reallocates the max memory size for a cache generation.

Resets the timer for pushing new cache generations.

Returns the PID of the GC server for the given server_ref.

Starts the garbage collector for the built-in local cache adapter.

Types

@type opts() :: Nebulex.Cache.opts()
@type server_ref() :: pid() | atom() | :ets.tid()
@type t() :: %Nebulex.Adapters.Local.Generation{
  allocated_memory: term(),
  backend: term(),
  backend_opts: term(),
  cache: term(),
  gc_cleanup_max_timeout: term(),
  gc_cleanup_min_timeout: term(),
  gc_cleanup_ref: term(),
  gc_flush_delay: term(),
  gc_heartbeat_ref: term(),
  gc_interval: term(),
  max_size: term(),
  meta_tab: term(),
  name: term(),
  stats_counter: term(),
  telemetry: term(),
  telemetry_prefix: term()
}

Functions

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec delete_all(server_ref()) :: integer()

Removes or flushes all entries from the cache (including all its generations).

Example

Nebulex.Adapters.Local.Generation.delete_all(MyCache)
@spec get_state(server_ref()) :: t()

A convenience function for retrieving the state.

@spec list(server_ref()) :: [:ets.tid()]

Returns the list of the generations in the form [newer, older].

Example

Nebulex.Adapters.Local.Generation.list(MyCache)
@spec memory_info(server_ref()) ::
  {used_mem :: non_neg_integer(), total_mem :: non_neg_integer()}

Returns the memory info in a tuple form {used_mem, total_mem}.

Example

Nebulex.Adapters.Local.Generation.memory_info(MyCache)
Link to this function

new(server_ref, opts \\ [])

View Source
@spec new(server_ref(), opts()) :: [atom()]

Creates a new cache generation. Once the max number of generations is reached, when a new generation is created, the oldest one is deleted.

Options

  • :reset_timer - Indicates if the poll frequency time-out should be reset or not (default: true).

Example

Nebulex.Adapters.Local.Generation.new(MyCache)

Nebulex.Adapters.Local.Generation.new(MyCache, reset_timer: false)
@spec newer(server_ref()) :: :ets.tid()

Returns the newer generation.

Example

Nebulex.Adapters.Local.Generation.newer(MyCache)
Link to this function

realloc(server_ref, size)

View Source
@spec realloc(server_ref(), pos_integer()) :: :ok

Reallocates the block of memory that was previously allocated for the given server_ref with the new size. In other words, reallocates the max memory size for a cache generation.

Example

Nebulex.Adapters.Local.Generation.realloc(MyCache, 1_000_000)

Resets the timer for pushing new cache generations.

Example

Nebulex.Adapters.Local.Generation.reset_timer(MyCache)
@spec server(server_ref()) :: pid()

Returns the PID of the GC server for the given server_ref.

Example

Nebulex.Adapters.Local.Generation.server(MyCache)
@spec start_link(opts()) :: GenServer.on_start()

Starts the garbage collector for the built-in local cache adapter.