https://github.com/dtolnay/inventory

Typed distributed plugin registration
https://github.com/dtolnay/inventory

Last synced: 11 days ago
JSON representation

Typed distributed plugin registration

• Host: GitHub
• URL: https://github.com/dtolnay/inventory
• Owner: dtolnay
• License: apache-2.0
• Created: 2018-12-24T16:39:22.000Z (almost 6 years ago)
• Default Branch: master
• Last Pushed: 2024-08-25T19:13:42.000Z (3 months ago)
• Last Synced: 2024-10-25T06:22:36.795Z (17 days ago)
• Language: Rust
• Homepage:
• Size: 227 KB
• Stars: 993
• Watchers: 11
• Forks: 43
• Open Issues: 4
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE-APACHE

Awesome Lists containing this project

README

        
## Typed distributed plugin registration

[](https://github.com/dtolnay/inventory)

[](https://crates.io/crates/inventory)

[](https://docs.rs/inventory)

[](https://github.com/dtolnay/inventory/actions?query=branch%3Amaster)

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.

```toml

[dependencies]

inventory = "0.3"

```

*Supports rustc 1.62+*




# 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.

[gflags]: https://gflags.github.io/gflags/

### 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!`.

```rust

pub struct Flag {

    short: char,

    name: &'static str,

    /* ... */

}

impl Flag {

    pub const 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.

```rust

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`.

```rust

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 runtime initialization functions similar to

`__attribute__((constructor))` in C, and similar to the [`ctor`] crate. 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.

[`ctor`]: https://github.com/mmastrac/rust-ctor

Platform support includes Linux, macOS, iOS, FreeBSD, Android, Windows, and a

few others. Beyond this, other platforms will simply find that no plugins have

been registered.

For a different approach to plugin registration that *does not* involve

life-before-main, see the [`linkme`] crate.

[`linkme`]: https://github.com/dtolnay/linkme




#### 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.