Cachex v3.1.3 Cachex.Spec View Source

Specification definitions based around records and utilities.

This serves as the “parent” header file for Cachex, where all records and macros are located. It’s designed as a single inclusion file which provides everything you might need to implement features in Cachex, and indeed when interacting with Cachex.

Most macros in here should be treated as reserved for internal use only, but those based around records can be freely used by consumers of Cachex.

Link to this section Summary

Types

cache()

command()

entry()

expiration()

fallback()

hook()

hooks()

limit()

warmer()

Functions

cache(args \\ [])

Creates a cache record from the provided values

cache(record, args)

Updates a cache record from the provided values

command(args \\ [])

Creates a command record from the provided values

command(record, args)

Updates a command record from the provided values

const(key)

Inserts constant values by a provided key

entry(args \\ [])

Creates an entry record from the provided values

entry(record, args)

Updates an entry record from the provided values

entry_idx(key)

Retrieves the ETS index for an entry field

entry_mod(updates)

Generates an ETS modification Tuple for entry field/value pairs

entry_mod_now(pairs \\ [])

Generates a list of ETS modification Tuples with an updated touch time

entry_now(pairs \\ [])

Creates an entry record with an updated touch time

expiration(args \\ [])

Creates an expiration record from the provided values

expiration(record, args)

Updates an expiration record from the provided values

fallback(args \\ [])

Creates a fallback record from the provided values

fallback(record, args)

Updates a fallback record from the provided values

hook(args \\ [])

Creates a hook record from the provided values

hook(record, args)

Updates a hook record from the provided values

hooks(args \\ [])

Creates a hooks collection record from the provided values

hooks(record, args)

Updates a hooks record from the provided values

is_negative_integer(integer)

Determines if a value is a negative integer

is_positive_integer(integer)

Determines if a value is a positive integer

limit(args \\ [])

Creates a limit record from the provided values

limit(record, args)

Updates a limit record from the provided values

name(name, service)

Generates a named atom for a cache, using the provided service

nillable?(nillable, condition)

Checks if a nillable value satisfies a provided condition

now()

Retrieves the current system time in milliseconds

service_call(cache, service, message)

Generates a service call for a cache

via(action, options)

Adds a :via delegation to a Keyword List

warmer(args \\ [])

Creates a warmer record from the provided values

warmer(record, args)

Updates a warmer record from the provided values

wrap(value, tag)

Wraps a value inside a tagged Tuple using the provided tag

Link to this section Types

cache()

cache() ::
  {:cache, atom(), map(), expiration(), fallback(), hooks(), limit(), [atom()],
   boolean(), [warmer()]}

command()

command() :: {:command, :read | :write, (any() -> any() | {any(), any()})}

entry()

entry() :: {:entry, any(), number(), number(), any()}

expiration()

expiration() :: {:expiration, integer(), integer(), boolean()}

fallback()

fallback() ::
  {:fallback, (any() -> any()) | (any(), any() -> any()), any()}

hook()

hook() :: {:hook, atom(), any(), GenServer.server()}

hooks()

hooks() :: {:hooks, [hook()], [hook()]}

limit()

limit() :: {:limit, integer(), atom(), number(), Keyword.t()}

warmer()

warmer() :: {:warmer, atom(), any()}

Link to this section Functions

cache(args \\ []) (macro)

Creates a cache record from the provided values.

A cache record is used to represent the internal state of a cache, and is used when executing calls. Most values in here will be other records defined in the main specification, and as such please see their documentation for further info.

cache(record, args) (macro)

cache(cache(), Keyword.t()) :: cache()

Updates a cache record from the provided values.

command(args \\ []) (macro)

Creates a command record from the provided values.

A command is a custom action which can be executed against a cache instance. They consist of a type (:read/:write) and an execution function. The type determines what form the execution should take.

In the case of a :read type, an execution function is a simple (any -> any) form, which will return the returned value directly to the caller. In the case of a :write type, an execution should be (any -> { any, any }) where the value in the left side of the returned Tuple will be returned to the caller, and the right side will be set inside the backing cache table.

command(record, args) (macro)

command(command(), Keyword.t()) :: command()

Updates a command record from the provided values.

const(key) (macro)

const(atom()) :: any()

Inserts constant values by a provided key.

Constants are meant to only be used internally as they may change without warning, but they are exposed as part of the spec interface all the same.

Constant blocks can use other constants in their definitions (as it’s all just macros under the hood, and happens at compile time).

entry(args \\ []) (macro)

Creates an entry record from the provided values.

An entry record reprents a single entry in a cache table.

Each entry has a key/value, along with a touch time and ttl. These records should never be used outside of the Cachex codebase other than when debugging, as they can change at any time and should be regarded as internal only.

entry(record, args) (macro)

entry(entry(), Keyword.t()) :: entry()

Updates an entry record from the provided values.

entry_idx(key) (macro)

entry_idx(atom()) :: integer()

Retrieves the ETS index for an entry field.

entry_mod(updates) (macro)

entry_mod({atom(), any()}) :: {integer(), any()}

Generates an ETS modification Tuple for entry field/value pairs.

This will convert the entry field name to the ETS index under the hood, and return it inside a Tuple with the provided value.

entry_mod_now(pairs \\ []) (macro)

entry_mod_now([{atom(), any()}]) :: [{integer(), any()}]

Generates a list of ETS modification Tuples with an updated touch time.

This will pass the arguments through and behave exactly as entry_mod/1 except that it will automatically update the :touched field in the entry to the current time.

entry_now(pairs \\ []) (macro)

entry_now([{atom(), any()}]) :: [{integer(), any()}]

Creates an entry record with an updated touch time.

This delegates through to entry/1, but ensures that the :touched field is set to the current time as a millisecond timestamp.

expiration(args \\ []) (macro)

Creates an expiration record from the provided values.

An expiration record contains properties defining expiration policies for a cache.

A default value can be provided which will then be added as a default TTL to all keys which do not have one set explicitly. This must be a valid millisecond integer.

The interval being controlled here is the Janitor service schedule; it controls how often the purge runs in the background of your application to remove expired records. This can be disabled completely by setting the value to nil. This is also a millisecond integer.

The lazy value determines whether or not records can be lazily removed on read. Since this is an expected behaviour it’s enabled by default, but there are cases where you might wish to disable it (such as when consistency isn’t that big an issue).

expiration(record, args) (macro)

expiration(expiration(), Keyword.t()) :: expiration()

Updates an expiration record from the provided values.

fallback(args \\ []) (macro)

Creates a fallback record from the provided values.

A fallback can consist of a nillable state to provide to a fallback defintion when requested (via a fallback with an arity of 2). If a default action is provided, it should be a function of arity 1 or 2, depending on if it requires the state or not.

fallback(record, args) (macro)

fallback(fallback(), Keyword.t()) :: fallback()

Updates a fallback record from the provided values.

hook(args \\ []) (macro)

Creates a hook record from the provided values.

Hook records contain the properties needed to start up a hook against a cache instance. There are several components in a hook record:

arguments to pass through to the hook init/1 callback.
a flag to set whether or not a hook should fire asynchronously.
the module name backing the hook, implementing the hook behaviour.
options to pass to the hook server instance (allowing for names, etc).
provisions to pass through to the hook provisioning callback.
a PID reference to a potentially running hook instance (optional).
the timeout to wait for a response when firing synchronous hooks.
the type of the hook (whether to fire before/after a request).

These values are mainly provided by the user, and this record might actually be replaced in future with just a behaviour and a set of macros (as this record is very noisy now).

hook(record, args) (macro)

hook(hook(), Keyword.t()) :: hook()

Updates a hook record from the provided values.

hooks(args \\ []) (macro)

Creates a hooks collection record from the provided values.

Hooks records are just a pre-sorted collection of hook records, grouped by their type so that notifications internally do not have to iterate and group manually.

hooks(record, args) (macro)

hooks(hooks(), Keyword.t()) :: hooks()

Updates a hooks record from the provided values.

is_negative_integer(integer) (macro)

is_negative_integer(integer()) :: boolean()

Determines if a value is a negative integer.

is_positive_integer(integer) (macro)

is_positive_integer(integer()) :: boolean()

Determines if a value is a positive integer.

limit(args \\ []) (macro)

Creates a limit record from the provided values.

A limit record represents size bounds on a cache, and the way size should be reclaimed.

A limit should have a valid integer as the maximum cache size, which is used to determine when to cull records. By default, an LRW style policy will be applied to remove old records but this can also be customized using the policy value. The amount of space to reclaim at once can be provided using the reclaim option.

You can also specify options to pass through to the policy server, in order to customize policy behaviour.

limit(record, args) (macro)

limit(limit(), Keyword.t()) :: limit()

Updates a limit record from the provided values.

name(name, service) (macro)

name(atom() | binary(), atom()) :: atom()

Generates a named atom for a cache, using the provided service.

The list of services is narrowly defined to avoid bloating the atom table as it’s not garbage collected. This macro is only used when naming services.

nillable?(nillable, condition) (macro)

nillable?(any(), (any() -> boolean())) :: boolean()

Checks if a nillable value satisfies a provided condition.

now() (macro)

now() :: integer()

Retrieves the current system time in milliseconds.

service_call(cache, service, message) (macro)

service_call(cache(), atom(), any()) :: any()

Generates a service call for a cache.

This will generate the service name for the provided cache and call the service with the provided message. The timeout for these service calls is :infinity as they’re all able to block the caller.

via(action, options) (macro)

via(atom(), Keyword.t()) :: Keyword.t()

Adds a :via delegation to a Keyword List.

warmer(args \\ []) (macro)

Creates a warmer record from the provided values.

A warmer record represents cache warmer processes to be run to populate keys.

A warmer should have a valid module provided, which correctly implements the behaviour associated with Cachex.Warmer. A state can also be provided, which will be passed to the execution callback of the provided module (which defaults to nil).

warmer(record, args) (macro)

warmer(warmer(), Keyword.t()) :: warmer()

Updates a warmer record from the provided values.

wrap(value, tag) (macro)

wrap(any(), atom()) :: {atom(), any()}

Wraps a value inside a tagged Tuple using the provided tag.