Localize.Locale.Loader (Localize v0.32.0)

A GenServer that serializes locale data loading to prevent race conditions.

When multiple processes request the same locale concurrently, the first request triggers the load and subsequent requests wait for it to complete. This avoids duplicate loads and redundant :persistent_term.put/2 calls (each of which triggers a global GC).

The server is started as part of the Localize supervision tree. All locale loading goes through load_and_store/2 which delegates to this server.

Summary

Functions

cache_store(entry)

Inserts a {cache_key, value} pair into the locale-validation cache via the owner GenServer.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

clear_cache()

Clears all entries from the locale-validation cache via the owner.

clear_locale_cache()

Clears the locale validation cache.

load_and_store(locale, options \\ [])

Loads and stores locale data, serialized through the GenServer.

start_link(options \\ [])

Starts the loader GenServer.

Functions

cache_store(entry)

@spec cache_store({term(), term()}) :: :ok

Inserts a {cache_key, value} pair into the locale-validation cache via the owner GenServer.

Sent as a cast/2 so the hot path never blocks on the owner's mailbox, and so a write originating inside the owner (e.g. when validate_locale/1 is called transitively from handle_call({:load_and_store, ...})) cannot deadlock. Eventual- consistency is acceptable for a cache: a write that hasn't landed yet just looks like a miss, which triggers a recompute.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

clear_cache()

@spec clear_cache() :: :ok

Clears all entries from the locale-validation cache via the owner.

clear_locale_cache()

@spec clear_locale_cache() :: :ok

Clears the locale validation cache.

This is called when the supported locales change to ensure stale resolutions are not returned.

load_and_store(locale, options \\ [])

@spec load_and_store(Localize.Locale.Provider.locale(), Keyword.t()) ::
  :ok | {:error, Exception.t()}

Loads and stores locale data, serialized through the GenServer.

If the locale is already loaded, returns :ok immediately without contacting the server. Otherwise, delegates to the GenServer which ensures only one load per locale occurs.

Arguments

locale is a locale identifier atom or a Localize.LanguageTag.t/0.
options is a keyword list of options.

Options

:provider is the module implementing Localize.Locale.Provider to use. The default is Localize.Locale.default_provider/0.

Returns

:ok on success.
{:error, exception} if the locale data could not be loaded.

start_link(options \\ [])

Starts the loader GenServer.