Macro rustler::rustler_atoms

macro_rules! rustler_atoms {
    {
        $(
            $( #[$attr:meta] )*
            atom $name:ident $( = $str:expr )*;
        )*
    } => { ... };
    { @internal_make_atom($env:ident, $name:ident) } => { ... };
    { @internal_make_atom($env:ident, $name:ident = $str:expr) } => { ... };
}

Macro for defining Rust functions that return Erlang atoms. To use this macro, you must also import the lazy_static crate.

For example, this code:

#[macro_use] extern crate rustler;
#[macro_use] extern crate lazy_static;

mod my_atoms {
    rustler_atoms! {
        atom jpeg;
    }
}

defines a public function my_atoms::jpeg() that returns the NifAtom for the jpeg atom.

Multiple atoms can be defined. Each one can have its own doc comment and other attributes.

rustler_atoms! {
    /// The `jpeg` atom.
    atom jpeg;

    /// The `png` atom.
    atom png;

    #[allow(non_snake_case)]
    atom WebP;
}

When you need an atom that's not a legal Rust function name, write atom NAME = "ATOM", like this:

rustler_atoms! {
    /// The `mod` atom. The function isn't called `mod` because that's
    /// a Rust keyword.
    atom mod_atom = "mod";

    /// The atom `'hello world'`. Obviously this function can't be
    /// called `hello world` because there's a space in it.
    atom hello_world = "hello world";
}

Performance

These functions are faster than get_atom and get_atom_init. The first time you call one, it creates atoms for all its sibling functions and caches them, so that all later calls are fast. The only overhead is checking that the atoms have been created (an atomic integer read).