https://github.com/afranchuk/plugin_tls

Thread-local storage across dynamic library boundaries in rust.
https://github.com/afranchuk/plugin_tls

plugin plugins rust thread-local thread-local-storage

Last synced: 2 months ago
JSON representation

Thread-local storage across dynamic library boundaries in rust.

• Host: GitHub
• URL: https://github.com/afranchuk/plugin_tls
• Owner: afranchuk
• License: mit
• Created: 2020-12-01T16:43:06.000Z (about 4 years ago)
• Default Branch: main
• Last Pushed: 2022-08-24T14:26:03.000Z (over 2 years ago)
• Last Synced: 2024-08-09T19:23:17.433Z (5 months ago)
• Topics: plugin, plugins, rust, thread-local, thread-local-storage
• Language: Rust
• Homepage:
• Size: 17.6 KB
• Stars: 3
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: ChangeLog.md
  • License: LICENSE

Awesome Lists containing this project

README

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