inventory

by dtolnay

dtolnay / inventory

Typed distributed plugin registration

279 Stars 14 Forks Last release: about 2 months ago (0.1.9) Other 56 Commits 10 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Typed distributed plugin registration

github crates.io docs.rs build status

This crate provides a way to set up a plugin registry into which plugins can be registered from any source file linked into your application. There does not need to be a central list of all the plugins.

[dependencies]
inventory = "0.1"

Supports rustc 1.31+


Examples

Suppose we are writing a command line flags library and want to allow any source file in the application to register command line flags that are relevant to it.

This is the flag registration style used by gflags and is better suited for large scale development than maintaining a single central list of flags, as the central list would become an endless source of merge conflicts in an application developed simultaneously by thousands of developers.

Instantiating the plugin registry

Let's use a

struct Flag
as the plugin type, which will contain the short name of the flag like
-v
, the full name like
--verbose
, and maybe other information like argument type and help text. We instantiate a plugin registry with an invocation of
inventory::collect!
.
pub struct Flag {
    short: char,
    name: &'static str,
    /* ... */
}

impl Flag { pub fn new(short: char, name: &'static str) -> Self { Flag { short, name } } }

inventory::collect!(Flag);

This

collect!
call must be in the same crate that defines the plugin type. This macro does not "run" anything so place it outside of any function body.

Registering plugins

Now any crate with access to the

Flag
type can register flags as a plugin. Plugins can be registered by the same crate that declares the plugin type, or by any downstream crate.
inventory::submit! {
    Flag::new('v', "verbose")
}

The

submit!
macro does not "run" anything so place it outside of any function body. In particular, note that all
submit!
invocations across all source files linked into your application all take effect simultaneously. A
submit!
invocation is not a statement that needs to be called from
main
in order to execute.

Iterating over plugins

The value

inventory::iter::
is an iterator with element type
&'static T
that iterates over all plugins registered of type
T
.
for flag in inventory::iter:: {
    println!("-{}, --{}", flag.short, flag.name);
}

There is no guarantee about the order that plugins of the same type are visited by the iterator. They may be visited in any order.


How it works

Inventory is built on the

ctor
crate which provides module initialization functions for Rust similar to

__attribute__((constructor))
in C. Each call to
inventory::submit!
produces a shim that evaluates the given expression and registers it into a registry of its corresponding type. This registration happens dynamically as part of life-before-main for statically linked elements. Elements brought in by a dynamically loaded library are registered at the time that dlopen occurs.

Platform support includes Linux, macOS, iOS, FreeBSD, Android, and Windows. Other platforms will simply find that no plugins have been registered. Support for other targets would need to be added in the

ctor
crate.


License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.


Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.