plugin_tls

Thread-local and static-duration storage support across dynamic-library boundaries.

Normally, a std::thread::LocalKey refers to a specific memory location in a single binary. This library adds support for thread-local storage across binaries by storing thread-local values in a shared map between a host and one or more plugins.

The library also adds support for static-duration (but necessarily lazily-initialized) storage across binary boundaries, since such an implementation is very similar to that of thread-local storage.

Use

Use the host feature to enable the host capabilities (in exactly one binary to be loaded in memory), and use the plugin feature to enable plugin capabilities (in zero or more binaries to be loaded).

In each plugin binary, call Context::initialize with the host context prior to any thread-local or static storage being accessed (typically as part of the binary startup routine). The host binary will default to the correct state, however this may be overwritten with initialize as well.

Besides that, the thread_local! macro works exactly like std::thread_local! for both the host and plugins, and lazy_static! works exactly like the lazy_static crate. Note that thread-local and static values are indexed by the given name, type, and module path, so these must not conflict. Also note that stored values must be abi-stable. Abi-stability is not enforced in LocalKey (e.g. with the abi_stable::StableAbi trait) for library flexibility, but use of the abi_stable crate is highly encouraged.

Note that both host and plugin may be enabled together, specifically for use in workspaces that may contain both the host and plugin(s).

Safety

If unloading plugins, one must ensure that any memory set by plugins in thread-local or static storage is removed (including any initial values!). In the future there could be additions to track which initial values are created by a particular plugin, but for now one solution is for the host to call Context::reset to clear all thread-local and static values.