# `Nebulex.Adapters.Local.Generation`
[🔗](https://github.com/elixir-nebulex/nebulex_local/blob/v3.0.0/lib/nebulex/adapters/local/generation.ex#L1)

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_cleanup_delay`
to allow time for these processes to complete their work without being
blocked.

# `opts`

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

# `server_ref`

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

# `t`

```elixir
@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()
}
```

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `delete_all`

```elixir
@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`

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

A convenience function for retrieving the state.

# `list`

```elixir
@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`

```elixir
@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`

```elixir
@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` (`t: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`

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

Returns the newer generation.

## Example

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

# `realloc`

```elixir
@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`

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

Resets the GC interval.

## Example

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

# `server`

```elixir
@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`

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

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*