micro-moka 0.1.0

# Micro Moka

[![GitHub Actions][gh-actions-badge]][gh-actions]
[![crates.io release][release-badge]][crate]
[![docs][docs-badge]][docs]

<!-- [![coverage status][coveralls-badge]][coveralls] -->

[![license][license-badge]](#license)

Micro Moka is a lightweight, single-threaded cache library for Rust. It is a fork of
[Mini Moka][mini-moka-git], stripped down to the bare essentials while keeping the
W-TinyLFU eviction policy.

Micro Moka provides a non-thread-safe cache implementation for single thread applications.

All caches perform a best-effort bounding of a hash map using an entry replacement
algorithm to determine which entries to evict when the capacity is exceeded.

[gh-actions-badge]: ./assets/build.svg
[release-badge]: ./assets/version.svg
[docs-badge]: ./assets/docs.svg
[license-badge]: ./assets/license.svg

<!-- [fossa-badge]: https://app.fossa.com/api/projects/git%2Bgithub.com%2Fmoka-rs%2Fmini-moka.svg?type=shield -->

[gh-actions]: https://github.com/moka-rs/micro-moka/actions?query=workflow%3ACI
[crate]: https://crates.io/crates/micro-moka
[docs]: https://docs.rs/micro-moka
[deps-rs]: https://deps.rs/repo/github/moka-rs/micro-moka
[moka-git]: https://github.com/moka-rs/moka
[mini-moka-git]: https://github.com/moka-rs/mini-moka
[caffeine-git]: https://github.com/ben-manes/caffeine

## Features

- A cache can be bounded by the maximum number of entries.
- Maintains near optimal hit ratio by using an entry replacement algorithms inspired
  by Caffeine:
  - Admission to a cache is controlled by the Least Frequently Used (LFU) policy.
  - Eviction from a cache is controlled by the Least Recently Used (LRU) policy.
  - [More details and some benchmark results are available here][tiny-lfu].

<!--
Mini Moka provides a rich and flexible feature set while maintaining high hit ratio
and a high level of concurrency for concurrent access. However, it may not be as fast
as other caches, especially those that focus on much smaller feature sets.

If you do not need features like: time to live, and size aware eviction, you may want
to take a look at the [Quick Cache][quick-cache] crate.
-->

[tiny-lfu]: https://github.com/moka-rs/moka/wiki#admission-and-eviction-policies

<!-- [quick-cache]: https://crates.io/crates/quick_cache -->

## Change Log

- [CHANGELOG.md](https://github.com/moka-rs/mini-moka/blob/main/CHANGELOG.md)

## Table of Contents

- [Micro Moka](#micro-moka)
  - [Features](#features)
  - [Change Log](#change-log)
  - [Table of Contents](#table-of-contents)
  - [Usage](#usage)
  - [Example: Basic Usage](#example-basic-usage)
  - [Minimum Supported Rust Versions](#minimum-supported-rust-versions)
  - [Developing Micro Moka](#developing-micro-moka)
  - [Credits](#credits)
    - [Caffeine](#caffeine)
  - [License](#license)

## Usage

Add this to your `Cargo.toml`:

```toml
[dependencies]
micro_moka = "0.1"
```

## Example: Basic Usage

Cache entries are manually added using `insert` method, and are stored in the cache
until either evicted or manually invalidated.

```rust
use micro_moka::unsync::Cache;

fn main() {
    // Create a cache that can store up to 10,000 entries.
    let mut cache = Cache::new(10_000);

    // Insert an entry.
    cache.insert("my_key", "my_value");

    // Get the entry.
    // get() returns Option<&V>, a reference to the stored value.
    if let Some(value) = cache.get(&"my_key") {
        println!("value: {}", value);
    }

    // Invalidate the entry.
    cache.invalidate(&"my_key");
}
```

## Minimum Supported Rust Versions

Micro Moka's minimum supported Rust versions (MSRV) are the followings:

| Feature          |           MSRV            |
| :--------------- | :-----------------------: |
| default features | Rust 1.76.0 (Feb 8, 2024) |

It will keep a rolling MSRV policy of at least 6 months. If only the default features
are enabled, MSRV will be updated conservatively. When using other features, MSRV
might be updated more frequently, up to the latest stable. In both cases, increasing
MSRV is _not_ considered a semver-breaking change.

## Developing Micro Moka

**Running All Tests**

To run all tests including doc tests on the README, use the following command:

```console
$ RUSTFLAGS='--cfg trybuild' cargo test --all-features
```

**Generating the Doc**

```console
$ cargo +nightly -Z unstable-options --config 'build.rustdocflags="--cfg docsrs"' \
    doc --no-deps
```

## Credits

### Caffeine

Micro Moka's architecture is heavily inspired by the [Caffeine][caffeine-git] library
for Java. Thanks go to Ben Manes and all contributors of Caffeine.

## License

Micro Moka is distributed under either of

- The MIT license
- The Apache License (Version 2.0)

at your option.

See [LICENSE-MIT](LICENSE-MIT) and [LICENSE-APACHE](LICENSE-APACHE) for details.