Search documentation of Localize

# Localize.Locale.Loader (Localize v0.39.0)

Copy Markdown View Source

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.