Brief

A basic Atom (string) registry for use with ID strings.

For when an application contains and passes around many constant strings (mainly de/serialized strings), this should reduce the overall memory footprint and slightly increase cache usage

Warning: The performance implications of this crate should be tested to ensure it's a good fit for your use-case. There are many sitatuations where such a caching mechanism is simply unnecessary and this crate may easily harm performance due to the memory allocation required to register an atom, as well as the hash-lookup.

Inspiration for this project:

• Use Arc instead of Vec - Logan Smith (YouTube/@_noisecode)
• Atom Tables - Microsoft Windows

Usage

Atoms can be created directly and either passed by ref into functions, or cloned to avoid Rust's ownership semantics.

use tomt_atom::Atom;

fn construct_example()
{
    // Create atoms directly with `new()` constructor
    let atom = Atom::new("My &'static str example");

    // `new()` accepts any type that implements `AsRef<str>`
    let atom = Atom::new(String::new("My owned String example"));
}

fn convert_example()
{
    // Atom supports `From<&str>` and `From<String>``
    let atom: Atom = "Another &'static str example".into();

    // This should help if you need pass atoms directly
    let result = function_accepting_atom("Quick convert example".into())
}

Ideally atoms should be registered into a global table. This will provide lookups to return an existing atom if present, or create one if not. Atoms on there own may reduce the overall memory footprint, but with a registry the same string will always yield the same atom.

use tomt_atom::*;

fn global_registry()
{
    // Use built-in global registry
    let accept = AtomRegistry::global().register("application/json");
    
    // Create your own registry to pass via a service
    let mimes = AtomRegistry::new();
    let accept = mimes.register("application/json");

    // Unregistering will remove the entry in the lookup table, but all existing
    // Atoms will remain valid, and may continue to be cloned and passed around
    mimes.unregister("application/json");
}

Registries are indirect, support Send/Sync and can be cheaply cloned. Cloned registries point to the same atom table and updates in one will be reflected in both.

Changelog

Contributing

Got some idea, feedback, question or found a bug? Feel free to open an issue at any time!

License

TOMT_Atom is dual-licensed under either:

• MIT License (in repository or from [source][licence-MIT-remote])
• Apache License, Version 2.0 (in repository or from source)

This means you can select the license you prefer! This dual-licensing approach is the de-facto standard in the Rust ecosystem and there are good reasons to include both.