ConCache

https://hexdocs.pm/con_cache
Admin
ConCache (Concurrent Cache) is an ETS-based key/value storage for Elixir with row-level synchronized...
Tokens:23,105
Snippets:247
Trust Score:9
Update:4 months ago
Show doc for...
Tokens:
Raw
### Start and Use ConCache

Source: https://hexdocs.pm/con_cache/ConCache.html

Demonstrates how to start a ConCache instance with a specific name and interval, and then perform basic put and get operations. Items do not expire in this example.

```Elixir
ConCache.start_link(name: :my_cache, ttl_check_interval: false)
ConCache.put(:my_cache, :foo, 1)
ConCache.get(:my_cache, :foo)  # 1copy
```

--------------------------------

### Starting ConCache with a Global Alias

Source: https://hexdocs.pm/con_cache/readme.html

Demonstrates how to start ConCache with a globally registered alias. This alias can then be used to access the cache.

```elixir
ConCache.start_link([], name: {:global, :some_alias})
```

--------------------------------

### Starting ConCache with Custom ETS Options

Source: https://hexdocs.pm/con_cache/readme.html

Demonstrates how to start ConCache with specific ETS options, such as naming the table, setting it as an ordered set, and enabling read/write concurrency.

```elixir
ConCache.start_link(ets_options: [
  :named_table,
  {:name, :test_name},
  :ordered_set,
  {:read_concurrency, true},
  {:write_concurrency, true},
  {:decentralized_counters, true},
  {:heir, heir_pid}
])
```

--------------------------------

### Starting ConCache with Options and GenServer Options

Source: https://hexdocs.pm/con_cache/changelog.html

When starting ConCache, provide options for ConCache itself and for the GenServer. The owner process PID can be used for direct interaction, but for supervised caches, use registered aliases.

```elixir
ConCache.start_link/0,1,2
```

```elixir
ConCache.start/0,1,2
```

--------------------------------

### Start ConCache Worker

Source: https://hexdocs.pm/con_cache/readme.html

Start a ConCache worker as part of your application's children in the supervisor. This example registers the cache under the name `:my_cache`.

```elixir
children = [
  {ConCache, [name: :my_cache, ttl_check_interval: false]},
  ...
]

Supervisor.start_link(children, options)
```

--------------------------------

### ConCache Child Specification Example

Source: https://hexdocs.pm/con_cache/ConCache-function-start_link.html

Example of how to include ConCache in a supervision tree by providing its child specification.

```elixir
{ConCache, [name: :my_cache, ttl_check_interval: false]}
```

--------------------------------

### Start ConCache with a Local Alias

Source: https://hexdocs.pm/con_cache/changelog.html

Starts a ConCache process and registers it locally with the given alias. Use this when the cache is accessed only within the same node.

```elixir
ConCache.start_link([], name: :my_cache)
```

--------------------------------

### start_link(options)

Source: https://hexdocs.pm/con_cache/ConCache.html

Starts the server and creates an ETS table for the cache. It supports various options for naming, TTL, callbacks, locking, and ETS table configuration.

```APIDOC
## start_link(options)

### Description
Starts the server and creates an ETS table. This function initializes the cache with specified options.

### Function Signature
```elixir
@spec start_link(options()) :: Supervisor.on_start()
```

### Options
* `{:name, atom}` - A name for the cache process.
* `{:ttl_check_interval, time_ms | false}` - The interval for checking TTL expiry. Must be a positive integer or `false` to disable.
* `{:global_ttl, time_ms | :infinity}` - The time after which an item expires. Updating an item extends its expiry time.
* `{:touch_on_read, true | false}` - Controls if reading an item extends its expiry time. Defaults to `false`.
* `{:callback, callback_fun}` - A function invoked after an item is inserted/updated, or before it is deleted.
* `{:acquire_lock_timeout, timeout_ms}` - The time to wait for a lock. Defaults to 5000ms.
* `{:ets_options, [ets_option]}` - Options for the underlying ETS process.
* `{:n_lock_partitions, pos_integer}` - The desired number of lock partitions.

### Supported ETS Options
* `:set` (default)
* `:ordered_set`
* `:bag`
* `:duplicate_bag`
* `:named_table`
* `:name`
* `:heir`
* `:write_concurrency`
* `:read_concurrency`
* `:decentralized_counters`

### Child Specification
To include the cache in a supervision tree, use the format `{ConCache, con_cache_options}`.
Example: `{ConCache, [name: :my_cache, ttl_check_interval: false]}`

### Expiry Configuration
To configure expiry, provide a positive integer for `:ttl_check_interval` and a `:global_ttl` value. TTL is extended on modifications by default, but this can be changed with `touch_on_read: true`. For granular control, use `ConCache.Item` structs. To prevent TTL updates on modification, set the `:ttl` field to `:no_update` in `ConCache.Item`.
```

--------------------------------

### Restarting ConCache for Test Isolation

Source: https://hexdocs.pm/con_cache/readme.html

Provides a setup function for tests that restarts the ConCache process. This ensures each test starts with an empty cache, preventing interference between tests.

```elixir
setup do
  Supervisor.terminate_child(con_cache_supervisor, ConCache)
  Supervisor.restart_child(con_cache_supervisor, ConCache)
  :ok
end
```

--------------------------------

### ConCache.start_link

Source: https://hexdocs.pm/con_cache/ConCache-function-start_link.html

Starts the ConCache server and creates an ETS table with configurable options. This function is typically used to initialize a cache instance.

```APIDOC
## ConCache.start_link(options)

### Description
Starts the server and creates an ETS table.

### Method
`start_link`

### Parameters
#### Options
- **`{:name, atom}`**: A name for the cache process.
- **`{:ttl_check_interval, time_ms | false}`**: Required. A check interval for TTL expiry. Provide a positive integer for expiry to work, or pass `false` to disable ttl checks.
- **`{:global_ttl, time_ms | :infinity}`**: The time after which an item expires. Updating the item extends its expiry time.
- **`{:touch_on_read, true | false}`**: Controls whether a read operation extends the expiry of items. Defaults to `false`.
- **`{:callback, callback_fun}`**: A function invoked after an item is inserted or updated, or before it is deleted.
- **`{:acquire_lock_timeout, timeout_ms}`**: The time a client process waits for the lock. Defaults to `5000`.
- **`{:ets_options, [ets_option]}`**: Options for the ETS process. Supported options include `:set`, `:ordered_set`, `:bag`, `:duplicate_bag`, `:named_table`, `:name`, `:heir`, `:write_concurrency`, `:read_concurrency`, `:decentralized_counters`.
- **`{:n_lock_partitions, pos_integer}`**: A positive integer representing the desired number of lock partitions.

### Child specification
To insert your cache into the supervision tree, pass the child specification in the shape of `{ConCache, con_cache_options}`. For example:
```elixir
{ConCache, [name: :my_cache, ttl_check_interval: false]}
```

### Expiry Configuration
To configure expiry, provide a positive integer for `:ttl_check_interval` (in milliseconds) and the `:global_ttl` option (default TTL time for items). TTL is extended on modifications by default, but this can be changed with `:touch_on_read: true`. For granular control, use `ConCache.Item` structs. Setting `:ttl` to `:no_update` in the struct prevents TTL extension on modification.

**Choosing `ttl_check_interval` time**: A lower value means more frequent purging (less memory, potential performance impact), while higher values mean less frequent purging (less pressure on processing, less precise expiry).
```

--------------------------------

### Start ConCache with a gproc Alias

Source: https://hexdocs.pm/con_cache/changelog.html

Starts a ConCache process and registers it globally using the gproc mechanism. This allows the cache to be accessed across different nodes in a distributed system.

```elixir
ConCache.start_link([], name: {:via, :gproc, :my_cache})
```

--------------------------------

### Start Multiple Caches with Unique IDs

Source: https://hexdocs.pm/con_cache/readme.html

Configures a supervisor to manage multiple ConCache instances with distinct IDs and global TTLs.

```elixir
def start(_type, _args) do
  Supervisor.start_link(
    [
      ...
      con_cache_child_spec(:my_cache_1, 100),
      con_cache_child_spec(:my_cache_2, 200)
      ...
    ],
    ...
  )
end

defp con_cache_child_spec(name, global_ttl) do
  Supervisor.child_spec(
    {
      ConCache,
      [
        name: name,
        ttl_check_interval: :timer.seconds(1),
        global_ttl: :timer.seconds(global_ttl)
      ]
    },
    id: {ConCache, name}
  )
end
```

--------------------------------

### Start ConCache Server

Source: https://hexdocs.pm/con_cache/ConCache.html

Starts the ConCache server process and initializes an ETS table. Options can be provided to configure naming, TTL checks, global TTL, read behavior, callbacks, lock timeouts, and ETS table properties.

```elixir
@spec start_link(options()) :: Supervisor.on_start()
```

--------------------------------

### start_link

Source: https://hexdocs.pm/con_cache/ConCache.html

Starts the ConCache server and creates an ETS table. It accepts a list of options to configure the cache's behavior, such as name, TTL, and concurrency settings.

```APIDOC
## start_link(options)

### Description
Starts the server and creates an ETS table.

### Function Signature
`start_link(options)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **options** (options()) - Required - A list of options to configure the cache. See the `options()` type for available settings.
```

--------------------------------

### Using ConCache with gproc Alias

Source: https://hexdocs.pm/con_cache/index.html

Shows how to start ConCache with a name registered via gproc and subsequently use this gproc-registered alias to perform cache operations.

```elixir
ConCache.start_link([], name: {:via, :gproc, :my_cache})
```

```elixir
ConCache.put({:via, :gproc, :my_cache}, :some_key, :some_value)
```

--------------------------------

### get

Source: https://hexdocs.pm/con_cache/ConCache.html

Reads an item from the cache.

```APIDOC
## get(cache_id, key)

### Description
Reads the item from the cache.

### Function Signature
`get(cache_id, key)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **cache_id** (t()) - Required - The identifier of the cache.
- **key** (key()) - Required - The key of the item to retrieve.
```

--------------------------------

### Add ConCache as an Application Dependency

Source: https://hexdocs.pm/con_cache/changelog.html

To use ConCache as a proper OTP application, add it to your `mix.exs` file under the `applications` key. This ensures ConCache processes start before your application.

```elixir
def application do
  [applications: [:con_cache, ...], ...]
end
```

--------------------------------

### ConCache Telemetry Event Handler

Source: https://hexdocs.pm/con_cache/readme.html

Example handler for ConCache telemetry events to track cache hit and miss ratios.

```elixir
defmodule MyApp.HitMissRatioTracker do
  require Logger

  def handle_event([:con_cache, :stats, :hit], _measurements, %{cache: %{name: cache_name}}, _config) do
    # ... aggregate hits
  end

  def handle_event([:con_cache, :stats, :miss], _measurements, %{cache: %{name: cache_name}}, _config) do
    # ... aggregate misses
  end
end
```

--------------------------------

### Basic ConCache Operations

Source: https://hexdocs.pm/con_cache/readme.html

Perform basic operations on a ConCache instance, such as putting, inserting new, getting, deleting, and checking the size of items. These operations run in the caller process.

```elixir
ConCache.put(:my_cache, :key, "value")         # inserts value or overwrites the old one
ConCache.insert_new(:my_cache, :key, "value")  # inserts value or returns {:error, :already_exists}
ConCache.get(:my_cache, :key)
ConCache.delete(:my_cache, :key)
ConCache.size(:my_cache)
```

--------------------------------

### ConCache Worker Specification in Supervision Tree

Source: https://hexdocs.pm/con_cache/changelog.html

Example of how to include ConCache as a worker in a supervision tree, specifying options including the process name.

```elixir
worker(ConCache, [con_cache_options, [name: ...]])
```

--------------------------------

### ConCache.get Function Signature

Source: https://hexdocs.pm/con_cache/ConCache-function-get.html

This snippet shows the specification for the `get` function within the ConCache module. It indicates the types of arguments expected and the type of value returned.

```elixir
get(t(), key()) :: value()
```

--------------------------------

### Get Cache Size

Source: https://hexdocs.pm/con_cache/ConCache-function-size.html

Returns the number of items stored in the cache. Use this function to check the current size of a cache instance.

```Elixir
size(cache_id) :: non_neg_integer()
```

--------------------------------

### ConCache isolated Function Specification and Usage Example

Source: https://hexdocs.pm/con_cache/ConCache.html

Provides the type specification for the isolated function and demonstrates its usage for performing isolated operations on cache keys, ensuring mutual exclusivity with other cache operations like updates.

```elixir
@spec isolated(t(), key(), nil | pos_integer(), (-> any())) :: any()

# Process A:
ConCache.isolated(:my_cache, :my_item_key, fn() -> ... end)

# Process B:
ConCache.update(:my_cache, :my_item, fn(old_value) -> ... end)copy
```

--------------------------------

### get(cache_id, key)

Source: https://hexdocs.pm/con_cache/ConCache-function-get.html

Reads an item from the cache using the provided cache ID and key. This operation is a 'dirty' read, meaning it does not block concurrent updates and does not affect the item's Time-To-Live (TTL) by default.

```APIDOC
## get(cache_id, key)

### Description
Reads the item from the cache using the specified cache identifier and key. This is a 'dirty' read, which means it does not block while another process is updating the same item, and it does not reset the item's TTL unless the `touch_on_read` option was enabled when the cache was initialized.

### Function Signature
`get(cache_id, key)`

### Parameters
#### Path Parameters
- **cache_id** (any) - Required - The identifier of the cache to read from.
- **key** (any) - Required - The key of the item to retrieve from the cache.

### Returns
- **value** (any) - The value of the item stored in the cache.
```

--------------------------------

### Clearing Cache Entries for Test Isolation

Source: https://hexdocs.pm/con_cache/readme.html

A setup function for tests that fetches all keys from the ETS table associated with a cache alias and deletes each entry. This provides a clean slate for each test.

```elixir
setup do
  :my_cache
  |> ConCache.ets
  |> :ets.tab2list
  |> Enum.each(fn({key, _}) -> ConCache.delete(:my_cache, key) end)

  :ok
end
```

--------------------------------

### Interface ConCache Using Local Alias

Source: https://hexdocs.pm/con_cache/changelog.html

Interacts with a ConCache instance using its locally registered alias. This is the standard way to perform operations after starting the cache with a name.

```elixir
ConCache.put(:my_cache, :some_key, :some_value)
```

```elixir
ConCache.get(:my_cache, :some_key)
```

--------------------------------

### Get or Store Item in ConCache

Source: https://hexdocs.pm/con_cache/readme.html

Retrieve an item from ConCache, or call a function to compute and store it if it doesn't exist. Ensures the function is executed only once for concurrent requests.

```elixir
# Returns existing value, or calls function and stores the result.
# If many processes simultaneously invoke this function for the same key, the function will be
# executed only once, with all others reading the value from cache.
ConCache.get_or_store(:my_cache, :key, fn() ->
  "initial_value"
end)
```

--------------------------------

### Isolated Execution Example

Source: https://hexdocs.pm/con_cache/ConCache-function-isolated.html

Demonstrates how to use ConCache.isolated for exclusive operations. This function ensures that the provided lambda is executed exclusively for a given cache ID and key, preventing concurrent modifications or reads.

```elixir
ConCache.isolated(:my_cache, :my_item_key, fn() ->
  # Your code here
end)
```

--------------------------------

### ConCache get Function Specification

Source: https://hexdocs.pm/con_cache/ConCache.html

Provides the type specification for the get function. It reads an item from the cache using a 'dirty' read that does not block.

```elixir
@spec get(t(), key()) :: value()
```

--------------------------------

### ConCache.start_link Function Specification

Source: https://hexdocs.pm/con_cache/ConCache-function-start_link.html

This is the specification for the start_link function, indicating its arguments and return type.

```elixir
start_link(options()) :: Supervisor.on_start()
```

--------------------------------

### Registering and Interfacing with a Supervised ConCache Instance

Source: https://hexdocs.pm/con_cache/changelog.html

For supervised ConCache instances, register the owner process locally and use the alias to interact with the cache. This is necessary because the owner process PID can change if restarted.

```elixir
ConCache.start_link/1
```

--------------------------------

### Get ets Table from ConCache

Source: https://hexdocs.pm/con_cache/ConCache-function-ets.html

Returns the ets table managed by the cache. This function is typically used for advanced debugging or integration purposes.

```Elixir
ets(cache_id) :: :ets.tab()
```

--------------------------------

### Configure ConCache with TTL

Source: https://hexdocs.pm/con_cache/readme.html

Sets up item expiry check interval and global expiry for all cache items.

```elixir
{ConCache, [
  name: :my_cache,
  ttl_check_interval: :timer.seconds(1),
  global_ttl: :timer.seconds(5)
]}
```

--------------------------------

### fetch_or_store

Source: https://hexdocs.pm/con_cache/ConCache.html

Retrieves an item from the cache. If the item does not exist, it is inserted using the provided `fetch_or_store_fun`.

```APIDOC
## fetch_or_store(cache_id, key, fetch_or_store_fun)

### Description
Retrieves the item from the cache, or inserts the new item.

### Function Signature
`fetch_or_store(cache_id, key, fetch_or_store_fun)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **cache_id** (t()) - Required - The identifier of the cache.
- **key** (key()) - Required - The key of the item.
- **fetch_or_store_fun** (fetch_or_store_fun()) - Required - A function that returns the value to store if the key does not exist.
```

--------------------------------

### fetch_or_store(cache_id, key, fetch_or_store_fun)

Source: https://hexdocs.pm/con_cache/ConCache-function-fetch_or_store.html

Retrieves the item from the cache by `cache_id` and `key`. If the item does not exist, it executes `fetch_or_store_fun`. If `fetch_or_store_fun` returns `{:ok, value}`, the value is stored in the cache and returned. If it returns `{:error, reason}`, the error is returned without caching. Any other return type from `fetch_or_store_fun` will raise a `RuntimeError`. The `fetch_or_store_fun` can return a plain value or a `%ConCache.Item{}` struct. This function is not supported for `:bag` or `:duplicate_bag` ETS tables.

```APIDOC
## fetch_or_store(cache_id, key, fetch_or_store_fun)

### Description
Retrieves an item from the cache using the provided `cache_id` and `key`. If the item is not found, it executes the `fetch_or_store_fun`. The result of `fetch_or_store_fun` is then cached if it's an `{:ok, value}` tuple. Otherwise, errors are returned or a `RuntimeError` is raised.

### Function Signature
`fetch_or_store(t(), key(), fetch_or_store_fun()) :: {:ok, value()} | {:error, any()}`

### Parameters
#### Path Parameters
* `cache_id` - (any) - The identifier for the cache table.
* `key` - (any) - The key under which the item is stored or to be stored.
* `fetch_or_store_fun` - (function) - A function that is called if the item is not found in the cache. It should return `{:ok, value}`, `{:error, reason}`, a plain value, or `%ConCache.Item{}`.

### Return Value
* `{:ok, value()}` - If the item was found in the cache or successfully fetched and stored.
* `{:error, any()}` - If the `fetch_or_store_fun` returned an error tuple.

### Raises
* `RuntimeError` - If `fetch_or_store_fun` returns a value that is not `{:ok, value}`, `{:error, reason}`, a plain value, or `%ConCache.Item{}`.

### Notes
* This function is not supported by `:bag` and `:duplicate_bag` ETS tables.
* When an item is already in the cache, this function performs a simple get operation without locking, ensuring high performance.
```

--------------------------------

### fetch_or_store/3

Source: https://hexdocs.pm/con_cache/ConCache.html

Retrieves an item from the cache, or inserts a new item if it doesn't exist. The new item is stored only if the fetch function returns `{:ok, value()}`.

```APIDOC
## fetch_or_store/3

### Description
Retrieves the item from the cache, or inserts the new item. If the item exists in the cache, it is retrieved. Otherwise, the lambda function is executed and its result is stored under the given key, but only if it returns an `{:ok, value}` tuple. If the `{:error, reason}` tuple is returned, caching is not done and the error becomes the result of the function. The lambda may return either a plain value or `%ConCache.Item{}`. This function is not supported by `:bag` and `:duplicate_bag` ETS tables. Emits `[:con_cache, :stats, :hit]` telemetry event if the item is found, and `[:con_cache, :stats, :miss]` otherwise.

### Function Signature
`fetch_or_store(cache_id, key, fetch_or_store_fun) :: {:ok, value()} | {:error, any()}`
```

--------------------------------

### get_or_store(cache_id, key, store_fun)

Source: https://hexdocs.pm/con_cache/ConCache-function-get_or_store.html

Retrieves an item from the cache associated with `cache_id` and `key`. If the item is not found, it executes the `store_fun` function, stores its result under the given key, and returns the result. The `store_fun` can return a plain value or a `%ConCache.Item{}` struct. This function is not supported for `:bag` and `:duplicate_bag` ETS table types. When an item is already in the cache, it performs a fast retrieval without locking.

```APIDOC
## get_or_store(cache_id, key, store_fun)

### Description
Retrieves the item from the cache, or inserts the new item. If the item exists in the cache, it is retrieved. Otherwise, the lambda function is executed and its result is stored under the given key. The lambda may return either a plain value or `%ConCache.Item{}`.

### Parameters
#### Path Parameters
- **cache_id** (any) - Required - The identifier for the cache.
- **key** (any) - Required - The key under which the item is stored or to be stored.
- **store_fun** (function) - Required - A function that generates the value to be stored if the key is not found in the cache.

### Notes
- This function is not supported by `:bag` and `:duplicate_bag` ETS tables.
- If the item is already in the cache, this function performs a simple get without any locking.
```

--------------------------------

### Attempting Isolated Operations with Immediate Lock Failure

Source: https://hexdocs.pm/con_cache/readme.html

Shows how to use `ConCache.try_isolated/3` which immediately returns `{:error, :locked}` if the lock cannot be acquired, unlike `ConCache.isolated/3` which would block.

```elixir
# Same as above, but immediately returns {:error, :locked} if lock could not be acquired.
ConCache.try_isolated(cache, my_lock_id, fn() ->
  ...
end)
```

--------------------------------

### get_or_store

Source: https://hexdocs.pm/con_cache/ConCache.html

Retrieves an item from the cache. If the item does not exist, it is inserted using the provided `store_fun`.

```APIDOC
## get_or_store(cache_id, key, store_fun)

### Description
Retrieves the item from the cache, or inserts the new item.

### Function Signature
`get_or_store(cache_id, key, store_fun)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **cache_id** (t()) - Required - The identifier of the cache.
- **key** (key()) - Required - The key of the item.
- **store_fun** (store_fun()) - Required - A function that returns the value to store if the key does not exist.
```

--------------------------------

### put

Source: https://hexdocs.pm/con_cache/ConCache.html

Stores an item into the cache. If the key already exists, its value will be overwritten.

```APIDOC
## put(cache_id, key, value)

### Description
Stores the item into the cache.

### Function Signature
`put(cache_id, key, value)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **cache_id** (t()) - Required - The identifier of the cache.
- **key** (key()) - Required - The key of the item to store.
- **value** (value()) - Required - The value of the item to store.
```

--------------------------------

### Configure ConCache with TTL and Touch on Read

Source: https://hexdocs.pm/con_cache/readme.html

Enables extending item lifetime on read operations.

```elixir
{ConCache, [
  name: :my_cache,
  ttl_check_interval: :timer.seconds(1),
  global_ttl: :timer.seconds(5),
  touch_on_read: true
]}
```

--------------------------------

### dirty_get_or_store/3

Source: https://hexdocs.pm/con_cache/ConCache-function-dirty_get_or_store.html

Retrieves a value from the cache using the provided key. If the key is not found, it calls the store_fun to compute and store the value before returning it. This is a 'dirty' equivalent, implying potential side effects or non-transactional behavior.

```APIDOC
## dirty_get_or_store(cache_id, key, store_fun)

### Description
Retrieves a value from the cache using the provided key. If the key is not found, it calls the `store_fun` to compute and store the value before returning it. This is a 'dirty' equivalent, implying potential side effects or non-transactional behavior.

### Function Signature
`dirty_get_or_store(t(), key(), store_fun()) :: value()`

### Parameters
#### Path Parameters
- **cache_id** (any) - Required - Identifier for the cache.
- **key** (any) - Required - The key to look up in the cache.
- **store_fun** (function) - Required - The function to call if the key is not found. This function should return the value to be stored and retrieved.
```

--------------------------------

### get/2

Source: https://hexdocs.pm/con_cache/ConCache.html

Reads an item from the cache. This is a 'dirty' read that does not block and does not expire the item's TTL unless `touch_on_read` is enabled.

```APIDOC
## get/2

### Description
Reads the item from the cache. A read is always "dirty", meaning it doesn't block while someone is updating the item under the same key. A read doesn't expire TTL of the item, unless `touch_on_read` option is set while starting the cache. Emits `[:con_cache, :stats, :hit]` telemetry event if the item is found, and `[:con_cache, :stats, :miss]` otherwise.

### Function Signature
`get(cache_id, key) :: value()`
```

--------------------------------

### ConCache.dirty_fetch_or_store Function Specification

Source: https://hexdocs.pm/con_cache/ConCache-function-dirty_fetch_or_store.html

This is the function specification for dirty_fetch_or_store. It outlines the expected input types and return values.

```elixir
dirty_fetch_or_store(t(), key(), fetch_or_store_fun()) ::
  {:ok, value()} | {:error, any()}
```

--------------------------------

### Direct ETS Insertion

Source: https://hexdocs.pm/con_cache/readme.html

Shows how to directly insert data into the ETS table using `:ets.insert/2`. This bypasses ConCache's additional behaviors like TTL and callbacks.

```elixir
:ets.insert(ConCache.ets(cache), {key, value})
```

--------------------------------

### Configure ConCache with Global TTL

Source: https://hexdocs.pm/con_cache/index.html

Sets up item expiry check interval and global expiry for all cache items. The item lifetime is renewed on modification.

```elixir
{ConCache, [
  name: :my_cache,
  ttl_check_interval: :timer.seconds(1),
  global_ttl: :timer.seconds(5)
]}copy

```

--------------------------------

### dirty_fetch_or_store

Source: https://hexdocs.pm/con_cache/ConCache.html

Dirty equivalent of `fetch_or_store/3`. Retrieves the item from the cache, or inserts a new item if it doesn't exist, without explicit synchronization.

```APIDOC
## dirty_fetch_or_store(cache_id, key, fetch_or_store_fun)

### Description
Dirty equivalent of `fetch_or_store/3`.

### Function Signature
`dirty_fetch_or_store(cache_id, key, fetch_or_store_fun)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **cache_id** (t()) - Required - The identifier of the cache.
- **key** (key()) - Required - The key of the item.
- **fetch_or_store_fun** (fetch_or_store_fun()) - Required - A function that returns the value to store if the key does not exist.
```

--------------------------------

### touch(cache_id, key)

Source: https://hexdocs.pm/con_cache/ConCache-function-touch.html

Manually touches the item to prolong its expiry. This function takes a cache ID and a key as arguments and returns :ok upon successful execution.

```APIDOC
## touch(cache_id, key)

### Description
Manually touches the item to prolongate its expiry.

### Parameters
#### Path Parameters
- **cache_id** (any) - Required - The identifier of the cache.
- **key** (any) - Required - The key of the item to touch.

### Response
#### Success Response (200)
- **status** (:ok) - Indicates the operation was successful.
```

--------------------------------

### dirty_fetch_or_store/3

Source: https://hexdocs.pm/con_cache/ConCache.html

Dirty equivalent of `fetch_or_store/3`. Retrieves an item from the cache or stores a new one if it doesn't exist, without blocking.

```APIDOC
## dirty_fetch_or_store/3

### Description
Dirty equivalent of `fetch_or_store/3`. Retrieves an item from the cache or stores a new one if it doesn't exist, without blocking.

### Function Signature
`dirty_fetch_or_store(cache_id, key, fetch_or_store_fun) :: {:ok, value()} | {:error, any()}`
```

--------------------------------

### get_or_store/3

Source: https://hexdocs.pm/con_cache/ConCache.html

Retrieves an item from the cache, or inserts a new item if it doesn't exist. The new item is stored regardless of the return value of the store function.

```APIDOC
## get_or_store/3

### Description
Retrieves the item from the cache, or inserts the new item. If the item exists in the cache, it is retrieved. Otherwise, the lambda function is executed and its result is stored under the given key. The lambda may return either a plain value or `%ConCache.Item{}`. This function is not supported by `:bag` and `:duplicate_bag` ETS tables. Emits `[:con_cache, :stats, :hit]` telemetry event if the item is found, and `[:con_cache, :stats, :miss]` otherwise.

### Function Signature
`get_or_store(cache_id, key, store_fun) :: value()`
```

--------------------------------

### ConCache.dirty_get_or_store Function Specification

Source: https://hexdocs.pm/con_cache/ConCache-function-dirty_get_or_store.html

This is the specification for the dirty_get_or_store function. It outlines the expected types for its arguments and return value.

```elixir
dirty_get_or_store(t(), key(), store_fun()) :: value()
```

--------------------------------

### ConCache.put Function Specification

Source: https://hexdocs.pm/con_cache/ConCache-function-put.html

This is the specification for the `put` function. It indicates the function takes a cache ID, a key, and a value, and returns :ok upon successful storage.

```elixir
put(t(), key(), store_value()) :: :ok
```

--------------------------------

### dirty_get_or_store/3

Source: https://hexdocs.pm/con_cache/ConCache.html

Dirty equivalent of `get_or_store/3`. Retrieves an item from the cache or stores a new one if it doesn't exist, without blocking.

```APIDOC
## dirty_get_or_store/3

### Description
Dirty equivalent of `get_or_store/3`. Retrieves an item from the cache or stores a new one if it doesn't exist, without blocking.

### Function Signature
`dirty_get_or_store(cache_id, key, store_fun) :: value()`
```

--------------------------------

### dirty_get_or_store

Source: https://hexdocs.pm/con_cache/ConCache.html

Dirty equivalent of `get_or_store/3`. Retrieves the item from the cache, or inserts a new item if it doesn't exist, without explicit synchronization.

```APIDOC
## dirty_get_or_store(cache_id, key, store_fun)

### Description
Dirty equivalent of `get_or_store/3`.

### Function Signature
`dirty_get_or_store(cache_id, key, store_fun)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **cache_id** (t()) - Required - The identifier of the cache.
- **key** (key()) - Required - The key of the item.
- **store_fun** (store_fun()) - Required - A function that returns the value to store if the key does not exist.
```

--------------------------------

### try_isolated(cache_id, key, timeout \ nil, on_success)

Source: https://hexdocs.pm/con_cache/ConCache.html

Attempts to acquire a lock for an item and execute a function, similar to `isolated/4`, but does not wait for the lock if it's not immediately available.

```APIDOC
## try_isolated(cache_id, key, timeout \ nil, on_success)

### Description
Attempts to acquire a lock for a given key and execute a success function. If the lock cannot be acquired immediately, it returns `{:error, :locked}` without waiting. This is a non-blocking alternative to `isolated/4`.

### Function Signature
```elixir
@spec try_isolated(t(), key(), nil | pos_integer(), (-> any())) ::
  {:error, :locked} | {:ok, any()}
```

### Parameters
* **cache_id** (t()) - The identifier of the cache.
* **key** (key()) - The key of the item to operate on.
* **timeout** (nil | pos_integer()) - The maximum time to wait for the lock. If `nil`, it attempts to acquire immediately.
* **on_success** (-> any()) - The function to execute if the lock is acquired. It should return a value that will be wrapped in `{:ok, value}`.
```

--------------------------------

### ConCache.dirty_update_existing Function Specification

Source: https://hexdocs.pm/con_cache/ConCache-function-dirty_update_existing.html

This is the function specification for `dirty_update_existing/3`. It outlines the function's arguments and possible return values.

```elixir
dirty_update_existing(t(), key(), update_fun()) ::
  :ok | {:error, :not_existing} | {:error, any()}
```

--------------------------------

### Options Type Definition

Source: https://hexdocs.pm/con_cache/ConCache.html

Defines the available options for configuring ConCache, including naming, TTL, timeouts, callbacks, and ETS-specific settings.

```Elixir
@type options() :: [
  name: atom(),
  global_ttl: non_neg_integer(),
  acquire_lock_timeout: pos_integer(),
  callback: callback_fun(),
  touch_on_read: boolean(),
  ttl_check_interval: non_neg_integer() | false,
  time_size: pos_integer(),
  ets_options: [ets_option()],
  n_lock_partitions: pos_integer()
]
```

--------------------------------

### Try Isolated Operation (Non-blocking)

Source: https://hexdocs.pm/con_cache/ConCache.html

Attempts to acquire a lock for a key and execute a function. If the lock cannot be acquired immediately, it returns an error without waiting. This is useful for operations where blocking is not desired.

```elixir
@spec try_isolated(t(), key(), nil | pos_integer(), (-> any())) ::
  {:error, :locked} | {:ok, any()}
```

--------------------------------

### try_isolated/4

Source: https://hexdocs.pm/con_cache/ConCache-function-try_isolated.html

Attempts to acquire a lock immediately for a given cache ID and key. If the lock is acquired, it invokes the provided success callback. If the lock cannot be acquired immediately, it returns an error.

```APIDOC
## try_isolated/4

### Description
Attempts to acquire a lock immediately for a given cache ID and key. If the lock is acquired, it invokes the provided success callback. If the lock cannot be acquired immediately, it returns an error.

### Function Signature
try_isolated(cache_id, key, timeout \ nil, on_success)

### Parameters

* `cache_id` - The identifier for the cache.
* `key` - The key associated with the lock.
* `timeout` - Optional. The maximum time to wait for the lock (defaults to nil).
* `on_success` - A callback function to be invoked if the lock is successfully acquired. It receives the result of the function execution.

### Returns

* `{:error, :locked}` - If the lock could not be acquired immediately.
* `{:ok, any()}` - If the lock was acquired and the function was invoked successfully, returning the result of the function.
```

--------------------------------

### ConCache.get_or_store Function Signature

Source: https://hexdocs.pm/con_cache/ConCache-function-get_or_store.html

This snippet shows the specification for the get_or_store function, indicating its arguments and return type.

```Elixir
get_or_store(t(), key(), store_fun()) :: value()
```

--------------------------------

### ConCache.dirty_insert_new Function Specification

Source: https://hexdocs.pm/con_cache/ConCache-function-dirty_insert_new.html

This is the function specification for dirty_insert_new. It indicates the function takes a cache ID, a key, and a value, and returns :ok on success or an error tuple if the key already exists.

```elixir
dirty_insert_new(t(), key(), store_value()) :: :ok | {:error, :already_exists}
```

--------------------------------

### ConCache.fetch_or_store Function Specification

Source: https://hexdocs.pm/con_cache/ConCache-function-fetch_or_store.html

This is the type specification for the fetch_or_store function. It indicates the expected input types and the possible return types: either an {:ok, value} tuple or an {:error, any()} tuple.

```Elixir
fetch_or_store(t(), key(), fetch_or_store_fun()) ::
  {:ok, value()} | {:error, any()}
```

--------------------------------

### dirty_update_existing/3

Source: https://hexdocs.pm/con_cache/ConCache-function-dirty_update_existing.html

Performs a dirty update on an existing cache entry. This function is the 'dirty' equivalent of `update_existing/3`, implying it might bypass some consistency checks for performance.

```APIDOC
## dirty_update_existing/3

### Description
Performs a dirty update on an existing cache entry. This function is the 'dirty' equivalent of `update_existing/3`, implying it might bypass some consistency checks for performance.

### Function Signature
`dirty_update_existing(cache_id, key, update_fun)`

### Parameters
#### Path Parameters
- **cache_id**: (type unspecified) - Description of cache_id
- **key**: (type unspecified) - Description of key
- **update_fun**: (type unspecified) - Description of update_fun

### Returns
- `:ok` - Indicates the update was successful.
- `{:error, :not_existing}` - Returned if the cache entry specified by `cache_id` and `key` does not exist.
- `{:error, any()}` - Returned for other types of errors during the update process.
```

--------------------------------

### dirty_fetch_or_store/3

Source: https://hexdocs.pm/con_cache/ConCache-function-dirty_fetch_or_store.html

Fetches a value from the cache or stores it if not found, using a provided function. This is the 'dirty' equivalent, implying potential side effects or non-transactional behavior.

```APIDOC
## dirty_fetch_or_store/3

### Description
Fetches a value from the cache associated with `cache_id` and `key`. If the value is not found, it calls `fetch_or_store_fun` to compute and store the value. This is a 'dirty' operation, meaning it might have side effects or not guarantee transactional consistency.

### Function Signature
`dirty_fetch_or_store(cache_id, key, fetch_or_store_fun)

### Parameters

*   **cache_id**: The identifier for the cache.
*   **key**: The key under which the value is stored or to be stored.
*   **fetch_or_store_fun**: A function that will be called to compute the value if it's not found in the cache. This function should return the value to be stored.

### Returns

*   `{:ok, value()}`: If the value was successfully fetched or stored.
*   `{:error, any()}`: If an error occurred during the fetch or store operation.
```

--------------------------------

### dirty_insert_new/3

Source: https://hexdocs.pm/con_cache/ConCache-function-dirty_insert_new.html

Inserts a new key-value pair into the cache if the key does not already exist. This is a 'dirty' equivalent, implying potential side effects or a less strict transactional behavior compared to a standard insert.

```APIDOC
## dirty_insert_new/3

### Description
Inserts a new key-value pair into the cache if the key does not already exist. This is a 'dirty' equivalent, implying potential side effects or a less strict transactional behavior compared to a standard insert.

### Function Signature
`dirty_insert_new(cache_id, key, value)`

### Parameters
#### Path Parameters
- **cache_id** (any) - Required - The identifier of the cache.
- **key** (any) - Required - The key to insert.
- **value** (any) - Required - The value to associate with the key.

### Return Value
- `:ok` - If the insertion was successful.
- `{:error, :already_exists}` - If the key already exists in the cache.
```

--------------------------------

### size

Source: https://hexdocs.pm/con_cache/ConCache.html

Returns the number of items currently stored in the cache.

```APIDOC
## size(cache_id)

### Description
Returns the number of items stored in the cache.

### Function Signature
`size(cache_id)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **cache_id** (t()) - Required - The identifier of the cache.
```

--------------------------------

### update(cache_id, key, update_fun)

Source: https://hexdocs.pm/con_cache/ConCache.html

Updates an existing item or stores a new item if it doesn't exist. The `update_fun` is executed after the item is locked, ensuring exclusive access for modification.

```APIDOC
## update(cache_id, key, update_fun)

### Description
Updates an item in the cache or inserts a new item if the key does not exist. The `update_fun` is executed while the item is locked, guaranteeing exclusive access. This function is not supported for `:bag` or `:duplicate_bag` ETS tables.

### Function Signature
```elixir
@spec update(t(), key(), update_fun()) :: :ok | {:error, any()}
```

### Parameters
* **cache_id** (t()) - The identifier of the cache.
* **key** (key()) - The key of the item to update or insert.
* **update_fun** (update_fun()) - A function that takes the current value (or `nil` if not existing) and returns `{:ok, new_value}` or `{:error, reason}`.

### Updater Function Return Values
* `{:ok, value}` - The `value` will be stored in the table.
* `{:error, reason}` - The value will not be stored, and `{:error, reason}` will be returned.
```

--------------------------------

### ConCache get_or_store Function Specification

Source: https://hexdocs.pm/con_cache/ConCache.html

Provides the type specification for the get_or_store function. It retrieves an item or inserts a new one if it doesn't exist.

```elixir
@spec get_or_store(t(), key(), store_fun()) :: value()
```

--------------------------------

### put/3

Source: https://hexdocs.pm/con_cache/ConCache.html

Stores or overwrites an item in the cache.

```APIDOC
## put/3

### Description
Stores the item into the cache.

### Function Signature
`put(cache_id, key, value) :: :ok`
```

--------------------------------

### Fetch or Store Item in ConCache

Source: https://hexdocs.pm/con_cache/readme.html

Similar to `get_or_store`, but specifically handles `:ok`/:`{:error, _}` tuples returned by the function. The value is cached only if the function returns an `:ok` tuple.

```elixir
# Similar to get_or_store/3 but works with :ok/:error tuples.
# The value is cached only if the function returns an :ok tuple.
ConCache.fetch_or_store(:my_cache, :key, fn ->
  case call_api() do
    # The processed value will be cached and returned as an :ok tuple.
    {:ok, data} -> {:ok, process_data(data)}
    # The error tuple is propagated to the caller.
    {:error, _reason} = error -> error
  end
end)
```

--------------------------------

### ConCache.insert_new Function Specification

Source: https://hexdocs.pm/con_cache/ConCache-function-insert_new.html

This is the function specification for insert_new. It indicates that the function takes a cache ID, a key, and a value, and returns either :ok or an error tuple if the key already exists.

```elixir
insert_new(t(), key(), store_value()) :: :ok | {:error, :already_exists}
```

--------------------------------

### ConCache.update_existing Function Specification

Source: https://hexdocs.pm/con_cache/ConCache-function-update_existing.html

This is the function specification for `update_existing/3`. It outlines the expected arguments and possible return values, including success and error states.

```elixir
update_existing(t(), key(), update_fun()) ::
  :ok | {:error, :not_existing} | {:error, any()}
```

--------------------------------

### Add ConCache Dependency

Source: https://hexdocs.pm/con_cache/readme.html

Add `con_cache` as a dependency in your `mix.exs` file to use it in your project.

```elixir
defp deps do
  [
    {:con_cache, "~> 1.0"},
    ...
  ]
end
```

--------------------------------

### dirty_insert_new/3

Source: https://hexdocs.pm/con_cache/ConCache.html

Dirty equivalent of `insert_new/3`. Inserts a new item into the cache only if it does not already exist.

```APIDOC
## dirty_insert_new/3

### Description
Dirty equivalent of `insert_new/3`. Inserts a new item into the cache only if it does not already exist.

### Function Signature
`dirty_insert_new(cache_id, key, value) :: :ok | {:error, :already_exists}`
```

--------------------------------

### size/1

Source: https://hexdocs.pm/con_cache/ConCache.html

Returns the number of items currently stored in the cache.

```APIDOC
## size/1

### Description
Returns the number of items stored in the cache.

### Function Signature
`size(cache_id) :: non_neg_integer()`
```

--------------------------------

### ConCache.dirty_delete Function Specification

Source: https://hexdocs.pm/con_cache/ConCache-function-dirty_delete.html

This is the specification for the `dirty_delete/2` function. It indicates the function takes a cache identifier and a key, and returns :ok.

```elixir
dirty_delete(t(), key()) :: :ok
```

--------------------------------

### update_existing(cache_id, key, update_fun)

Source: https://hexdocs.pm/con_cache/ConCache-function-update_existing.html

Updates the item associated with `cache_id` and `key` using the provided `update_fun`. The update only occurs if the item already exists in the cache. If the item does not exist, the behavior is similar to `ConCache.update/3`.

```APIDOC
## update_existing(cache_id, key, update_fun)

### Description
Updates the item only if it exists. Otherwise works just like `update/3`.

### Function Signature
`update_existing(t(), key(), update_fun()) :: :ok | {:error, :not_existing} | {:error, any()}`

### Parameters
#### Path Parameters
- **cache_id** (t()) - The identifier of the cache.
- **key** (key()) - The key of the item to update.
- **update_fun** (update_fun()) - A function that takes the current value and returns the new value.

### Returns
- `:ok` - If the update was successful.
- `{:error, :not_existing}` - If the item with the given `cache_id` and `key` does not exist.
- `{:error, any()}` - If any other error occurred during the update process.
```
Tokens:
Raw