Expand description
Typed distributed plugin registration.
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.
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::<T> is an iterator with element type &'static T that iterates over all plugins registered of type T.
for flag in inventory::iter::<Flag> {
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.