Nebulex.Adapters.Local.Generation (nebulex_local v3.0.0-rc.1)
View SourceThis 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
@type opts() :: Nebulex.Cache.opts()
@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
Returns a specification to start this module under a supervisor.
See Supervisor
.
@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)
@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)
@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 istrue
.
Example
Nebulex.Adapters.Local.Generation.new(MyCache)
Nebulex.Adapters.Local.Generation.new(MyCache, gc_interval_reset: false)
@spec newer(server_ref()) :: :ets.tid()
Returns the newer generation.
Example
Nebulex.Adapters.Local.Generation.newer(MyCache)
@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)
@spec reset_gc_interval(server_ref()) :: :ok
Resets the GC interval.
Example
Nebulex.Adapters.Local.Generation.reset_gc_interval(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.