# `Localize.Locale.Loader`
[🔗](https://github.com/elixir-localize/localize/blob/v0.32.0/lib/localize/locale/loader.ex#L1)

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.

# `cache_store`

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

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `clear_cache`

```elixir
@spec clear_cache() :: :ok
```

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

# `clear_locale_cache`

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

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

Starts the loader GenServer.

---

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