Task local data management
Allows storing boxes with arbitrary types inside, to be accessed anywhere within a task, keyed by a pointer to a global finaliser function. Useful for dynamic variables, singletons, and interfacing with foreign code with bad callback interfaces.
To use, declare a monomorphic global function at the type to store, and use it as the 'key' when accessing. See the 'tls' tests below for examples.
Casting 'Arcane Sight' reveals an overwhelming aura of Transmutation magic.
LocalDataKey
- Indexes a task-local data slotlocal_data_get
- Retrieve a task-local data valuelocal_data_modify
- Modify a task-local data valuelocal_data_pop
- Remove a task-local data value from the table, returning the reference that was originally created to insert it.local_data_set
- Store a value in task-local dataLocalDataKey
type LocalDataKey<'self, T> = &'self fn: Copy(v: @T)
Indexes a task-local data slot. The function's code pointer is used for comparison. Recommended use is to write an empty function for each desired task-local data slot (and use class destructors, not code inside the function, if specific teardown is needed). DO NOT use multiple instantiations of a single polymorphic function to index data of different types; arbitrary type coercion is possible this way.
One other exception is that this global state can be used in a destructor context to create a circular @-box reference, which will crash during task failure (see issue #3039).
These two cases aside, the interface is safe.
local_data_get
unsafe fn local_data_get<T: 'static>(key: LocalDataKey<T>) -> Option<@T>
Retrieve a task-local data value. It will also be kept alive in the table until explicitly removed.
local_data_modify
unsafe fn local_data_modify<T: 'static>(key: LocalDataKey<T>,
modify_fn:
&fn(Option<@T>) -> Option<@T>)
Modify a task-local data value. If the function returns 'None', the data is removed (and its reference dropped).
local_data_pop
unsafe fn local_data_pop<T: 'static>(key: LocalDataKey<T>) -> Option<@T>
Remove a task-local data value from the table, returning the reference that was originally created to insert it.
local_data_set
unsafe fn local_data_set<T: 'static>(key: LocalDataKey<T>, data: @T)
Store a value in task-local data. If this key already has a value, that value is overwritten (and its destructor is run).