Nebulex.Adapters.Local.Generation (nebulex_local v3.1.0)

This module implements the generation manager and garbage collector.

The generation manager creates cache generations and schedules the deletion of retired generation tables. The adapter stores new entries in the newer generation and promotes entries from the older generation when they are fetched.

Generations rotate on the configured :gc_interval, when a size or memory check reaches its threshold, or when a caller explicitly requests a new generation.

When a new generation is created, the oldest one is removed from the active generations at once, so new operations no longer see it. Its tables are deleted after :gc_cleanup_delay, which gives operations that already hold a reference to them time to finish.

Summary

Types

opts()

server_ref()

t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

delete_all(server_ref)

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

get_state(server_ref)

A convenience function for retrieving the state.

list(server_ref)

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

memory_info(server_ref)

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

new(server_ref, opts \\ [])

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

newer(server_ref)

Returns the newer generation.

realloc(server_ref, size)

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.

reset_gc_interval(server_ref)

Resets the GC interval.

server(server_ref)

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

start_link(opts)

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_cleanup_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()) :: :ok

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.