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.

Type LocalDataKey

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.

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

Function 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).

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

Function 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).