Nebulex.Adapters.Local.Generation (nebulex_local v3.0.0-rc.1)

View Source

This module implements the generation manager and garbage collector.

The generational garbage collector manages the heap as several sub-heaps, known as generations, based on the 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, a new cache generation is created, and the oldest one is deleted.

The GC is triggered upon the following events:

  • When the :gc_interval times outs.
  • When the scheduled memory check times out. The memory check is executed when the :max_size or :allocated_memory options (or both) are configured. Furthermore, the memory check interval is determined by option :gc_memory_check_interval.

The oldest generation is deleted 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 the next GC run. However, flushing is a blocking operation. Once started, processes wanting to access the table must wait until it finishes. To circumvent this, the flush can be delayed by configuring :gc_flush_delay to allow time for these processes to complete their work without being blocked.

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 GC interval.

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

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

Types

opts()

@type opts() :: Nebulex.Cache.opts()

server_ref()

@type server_ref() :: pid() | atom() | :ets.tid()

t()

@type t() :: %Nebulex.Adapters.Local.Generation{
  allocated_memory: term(),
  backend: term(),
  backend_opts: term(),
  cache: term(),
  gc_flush_delay: term(),
  gc_healthcheck_ref: term(),
  gc_heartbeat_ref: term(),
  gc_interval: term(),
  gc_memory_check_interval: term(),
  max_size: term(),
  meta_tab: term(),
  name: term(),
  stats_counter: term(),
  telemetry: term(),
  telemetry_prefix: term()
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

delete_all(server_ref)

@spec delete_all(server_ref()) :: :ok

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

Example

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

get_state(server_ref)

@spec get_state(server_ref()) :: t()

A convenience function for retrieving the state.

list(server_ref)

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

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

Example

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

memory_info(server_ref)

@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)

new(server_ref, opts \\ [])

@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

  • :gc_interval_reset (boolean/0) - Whether the :gc_interval should be reset or not. The default value is true.

Example

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

Nebulex.Adapters.Local.Generation.new(MyCache, gc_interval_reset: false)

newer(server_ref)

@spec newer(server_ref()) :: :ets.tid()

Returns the newer generation.

Example

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

realloc(server_ref, size)

@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)

reset_gc_interval(server_ref)

@spec reset_gc_interval(server_ref()) :: :ok

Resets the GC interval.

Example

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

server(server_ref)

@spec server(server_ref()) :: pid()

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

Example

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

start_link(opts)

@spec start_link(opts()) :: GenServer.on_start()

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