1 // Copyright 2012-2013 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
13 Task local data management
15 Allows storing arbitrary types inside task-local-storage (TLS), to be accessed
16 anywhere within a task, keyed by a global pointer parameterized over the type of
17 the TLS slot. Useful for dynamic variables, singletons, and interfacing with
18 foreign code with bad callback interfaces.
20 To declare a new key for storing local data of a particular type, use the
21 `local_data_key!` macro. This macro will expand to a `static` item appropriately
22 named and annotated. This name is then passed to the functions in this module to
23 modify/read the slot specified by the key.
28 local_data_key!(key_int: int)
29 local_data_key!(key_vector: ~[int])
31 local_data::set(key_int, 3);
32 local_data::get(key_int, |opt| assert_eq!(opt.map(|x| *x), Some(3)));
34 local_data::set(key_vector, ~[4]);
35 local_data::get(key_vector, |opt| assert_eq!(*opt.unwrap(), ~[4]));
40 // Casting 'Arcane Sight' reveals an overwhelming aura of Transmutation
47 use option::{None, Option, Some};
49 use rt::task::{Task, LocalStorage};
50 use slice::{ImmutableVector, MutableVector};
54 * Indexes a task-local data slot. This pointer is used for comparison to
55 * differentiate keys from one another. The actual type `T` is not used anywhere
56 * as a member of this type, except that it is parameterized with it to define
57 * the type of each key's value.
59 * The value of each Key is of the singleton enum KeyValue. These also have the
60 * same name as `Key` and their purpose is to take up space in the programs data
61 * sections to ensure that each value of the `Key` type points to a unique
64 pub type Key<T> = &'static KeyValue<T>;
67 pub enum KeyValue<T> { Key }
71 impl<T: 'static> LocalData for T {}
73 // The task-local-map stores all TLS information for the currently running task.
74 // It is stored as an owned pointer into the runtime, and it's only allocated
75 // when TLS is used for the first time. This map must be very carefully
76 // constructed because it has many mutable loans unsoundly handed out on it to
77 // the various invocations of TLS requests.
79 // One of the most important operations is loaning a value via `get` to a
80 // caller. In doing so, the slot that the TLS entry is occupying cannot be
81 // invalidated because upon returning its loan state must be updated. Currently
82 // the TLS map is a vector, but this is possibly dangerous because the vector
83 // can be reallocated/moved when new values are pushed onto it.
85 // This problem currently isn't solved in a very elegant way. Inside the `get`
86 // function, it internally "invalidates" all references after the loan is
87 // finished and looks up into the vector again. In theory this will prevent
88 // pointers from being moved under our feet so long as LLVM doesn't go too crazy
89 // with the optimizations.
91 // n.b. If TLS is used heavily in future, this could be made more efficient with
94 pub type Map = Vec<Option<(*u8, TLSValue, LoanState)>>;
95 type TLSValue = Box<LocalData:Send>;
97 // Gets the map from the runtime. Lazily initialises if not done so already.
98 unsafe fn get_local_map() -> &mut Map {
101 let task: *mut Task = Local::unsafe_borrow();
102 match &mut (*task).storage {
103 // If the at_exit function is already set, then we just need to take
104 // a loan out on the TLS map stored inside
105 &LocalStorage(Some(ref mut map_ptr)) => {
108 // If this is the first time we've accessed TLS, perform similar
109 // actions to the oldsched way of doing things.
110 &LocalStorage(ref mut slot) => {
111 *slot = Some(vec!());
113 Some(ref mut map_ptr) => { return map_ptr }
122 NoLoan, ImmLoan, MutLoan
126 fn describe(&self) -> &'static str {
129 ImmLoan => "immutable",
135 fn key_to_key_value<T: 'static>(key: Key<T>) -> *u8 {
136 unsafe { cast::transmute(key) }
139 /// Removes a task-local value from task-local storage. This will return
140 /// Some(value) if the key was present in TLS, otherwise it will return None.
142 /// A runtime assertion will be triggered it removal of TLS value is attempted
143 /// while the value is still loaned out via `get` or `get_mut`.
144 pub fn pop<T: 'static>(key: Key<T>) -> Option<T> {
145 let map = unsafe { get_local_map() };
146 let key_value = key_to_key_value(key);
148 for entry in map.mut_iter() {
150 Some((k, _, loan)) if k == key_value => {
152 fail!("TLS value cannot be removed because it is currently \
153 borrowed as {}", loan.describe());
155 // Move the data out of the `entry` slot via prelude::replace.
156 // This is guaranteed to succeed because we already matched
158 let data = match replace(entry, None) {
159 Some((_, data, _)) => data,
163 // Move `data` into transmute to get out the memory that it
164 // owns, we must free it manually later.
165 let (_vtable, alloc): (uint, Box<T>) = unsafe {
166 cast::transmute(data)
169 // Now that we own `alloc`, we can just move out of it as we
170 // would with any other data.
179 /// Retrieves a value from TLS. The closure provided is yielded `Some` of a
180 /// reference to the value located in TLS if one exists, or `None` if the key
181 /// provided is not present in TLS currently.
183 /// It is considered a runtime error to attempt to get a value which is already
184 /// on loan via the `get_mut` method provided.
185 pub fn get<T: 'static, U>(key: Key<T>, f: |Option<&T>| -> U) -> U {
186 get_with(key, ImmLoan, f)
189 /// Retrieves a mutable value from TLS. The closure provided is yielded `Some`
190 /// of a reference to the mutable value located in TLS if one exists, or `None`
191 /// if the key provided is not present in TLS currently.
193 /// It is considered a runtime error to attempt to get a value which is already
194 /// on loan via this or the `get` methods.
195 pub fn get_mut<T: 'static, U>(key: Key<T>, f: |Option<&mut T>| -> U) -> U {
196 get_with(key, MutLoan, |x| {
199 // We're violating a lot of compiler guarantees with this
200 // invocation of `transmute`, but we're doing runtime checks to
201 // ensure that it's always valid (only one at a time).
203 // there is no need to be upset!
204 Some(x) => { f(Some(unsafe { cast::transmute::<&_, &mut _>(x) })) }
209 fn get_with<T:'static,
213 f: |Option<&T>| -> U)
215 // This function must be extremely careful. Because TLS can store owned
216 // values, and we must have some form of `get` function other than `pop`,
217 // this function has to give a `&` reference back to the caller.
219 // One option is to return the reference, but this cannot be sound because
220 // the actual lifetime of the object is not known. The slot in TLS could not
221 // be modified until the object goes out of scope, but the TLS code cannot
222 // know when this happens.
224 // For this reason, the reference is yielded to a specified closure. This
225 // way the TLS code knows exactly what the lifetime of the yielded pointer
226 // is, allowing callers to acquire references to owned data. This is also
227 // sound so long as measures are taken to ensure that while a TLS slot is
228 // loaned out to a caller, it's not modified recursively.
229 let map = unsafe { get_local_map() };
230 let key_value = key_to_key_value(key);
232 let pos = map.iter().position(|entry| {
234 Some((k, _, _)) if k == key_value => true, _ => false
238 None => { return f(None); }
241 let mut return_loan = false;
242 match *map.get_mut(i) {
243 Some((_, ref data, ref mut loan)) => {
244 match (state, *loan) {
249 (ImmLoan, ImmLoan) => {}
251 fail!("TLS slot cannot be borrowed as {} because \
252 it is already borrowed as {}",
253 want.describe(), cur.describe());
256 // data was created with `box T as Box<LocalData>`, so we
257 // extract pointer part of the trait, (as Box<T>), and
258 // then use compiler coercions to achieve a '&' pointer.
260 match *cast::transmute::<&TLSValue,
261 &(uint, Box<T>)>(data){
262 (_vtable, ref alloc) => {
263 let value: &T = *alloc;
264 ret = f(Some(value));
272 // n.b. 'data' and 'loans' are both invalid pointers at the point
273 // 'f' returned because `f` could have appended more TLS items which
274 // in turn relocated the vector. Hence we do another lookup here to
277 match *map.get_mut(i) {
278 Some((_, _, ref mut loan)) => { *loan = NoLoan; }
289 unsafe { intrinsics::abort() }
292 /// Inserts a value into task local storage. If the key is already present in
293 /// TLS, then the previous value is removed and replaced with the provided data.
295 /// It is considered a runtime error to attempt to set a key which is currently
296 /// on loan via the `get` or `get_mut` methods.
297 pub fn set<T: 'static>(key: Key<T>, data: T) {
298 let map = unsafe { get_local_map() };
299 let keyval = key_to_key_value(key);
301 // When the task-local map is destroyed, all the data needs to be cleaned
302 // up. For this reason we can't do some clever tricks to store 'Box<T>' as
303 // a '*c_void' or something like that. To solve the problem, we cast
304 // everything to a trait (LocalData) which is then stored inside the map.
305 // Upon destruction of the map, all the objects will be destroyed and the
306 // traits have enough information about them to destroy themselves.
307 let data = box data as Box<LocalData:>;
309 fn insertion_position(map: &mut Map,
310 key: *u8) -> Option<uint> {
311 // First see if the map contains this key already
312 let curspot = map.iter().position(|entry| {
314 Some((ekey, _, loan)) if key == ekey => {
316 fail!("TLS value cannot be overwritten because it is
317 already borrowed as {}", loan.describe())
324 // If it doesn't contain the key, just find a slot that's None
327 None => map.iter().position(|entry| entry.is_none())
331 // The type of the local data map must ascribe to Send, so we do the
332 // transmute here to add the Send bound back on. This doesn't actually
333 // matter because TLS will always own the data (until its moved out) and
334 // we're not actually sending it to other schedulers or anything.
335 let data: Box<LocalData:Send> = unsafe { cast::transmute(data) };
336 match insertion_position(map, keyval) {
337 Some(i) => { *map.get_mut(i) = Some((keyval, data, NoLoan)); }
338 None => { map.push(Some((keyval, data, NoLoan))); }
342 /// Modifies a task-local value by temporarily removing it from task-local
343 /// storage and then re-inserting if `Some` is returned from the closure.
345 /// This function will have the same runtime errors as generated from `pop` and
346 /// `set` (the key must not currently be on loan
347 pub fn modify<T: 'static>(key: Key<T>, f: |Option<T>| -> Option<T>) {
349 Some(next) => { set(key, next); }
363 fn test_tls_multitask() {
364 static my_key: Key<~str> = &Key;
365 set(my_key, "parent data".to_owned());
367 // TLS shouldn't carry over.
368 assert!(get(my_key, |k| k.map(|k| (*k).clone())).is_none());
369 set(my_key, "child data".to_owned());
370 assert!(get(my_key, |k| k.map(|k| (*k).clone())).unwrap() ==
371 "child data".to_owned());
372 // should be cleaned up for us
374 // Must work multiple times
375 assert!(get(my_key, |k| k.map(|k| (*k).clone())).unwrap() == "parent data".to_owned());
376 assert!(get(my_key, |k| k.map(|k| (*k).clone())).unwrap() == "parent data".to_owned());
377 assert!(get(my_key, |k| k.map(|k| (*k).clone())).unwrap() == "parent data".to_owned());
381 fn test_tls_overwrite() {
382 static my_key: Key<~str> = &Key;
383 set(my_key, "first data".to_owned());
384 set(my_key, "next data".to_owned()); // Shouldn't leak.
385 assert!(get(my_key, |k| k.map(|k| (*k).clone())).unwrap() == "next data".to_owned());
390 static my_key: Key<~str> = &Key;
391 set(my_key, "weasel".to_owned());
392 assert!(pop(my_key).unwrap() == "weasel".to_owned());
393 // Pop must remove the data from the map.
394 assert!(pop(my_key).is_none());
398 fn test_tls_modify() {
399 static my_key: Key<~str> = &Key;
400 modify(my_key, |data| {
402 Some(ref val) => fail!("unwelcome value: {}", *val),
403 None => Some("first data".to_owned())
406 modify(my_key, |data| {
407 match data.as_ref().map(|s| s.as_slice()) {
408 Some("first data") => Some("next data".to_owned()),
409 Some(ref val) => fail!("wrong value: {}", *val),
410 None => fail!("missing value")
413 assert!(pop(my_key).unwrap() == "next data".to_owned());
417 fn test_tls_crust_automorestack_memorial_bug() {
418 // This might result in a stack-canary clobber if the runtime fails to
419 // set sp_limit to 0 when calling the cleanup extern - it might
420 // automatically jump over to the rust stack, which causes next_c_sp
421 // to get recorded as something within a rust stack segment. Then a
422 // subsequent upcall (esp. for logging, think vsnprintf) would run on
423 // a stack smaller than 1 MB.
424 static my_key: Key<~str> = &Key;
426 set(my_key, "hax".to_owned());
431 fn test_tls_multiple_types() {
432 static str_key: Key<~str> = &Key;
433 static box_key: Key<@()> = &Key;
434 static int_key: Key<int> = &Key;
436 set(str_key, "string data".to_owned());
444 fn test_tls_overwrite_multiple_types() {
445 static str_key: Key<~str> = &Key;
446 static box_key: Key<@()> = &Key;
447 static int_key: Key<int> = &Key;
449 set(str_key, "string data".to_owned());
450 set(str_key, "string data 2".to_owned());
454 // This could cause a segfault if overwriting-destruction is done
455 // with the crazy polymorphic transmute rather than the provided
463 fn test_tls_cleanup_on_failure() {
464 static str_key: Key<~str> = &Key;
465 static box_key: Key<@()> = &Key;
466 static int_key: Key<int> = &Key;
467 set(str_key, "parent data".to_owned());
471 set(str_key, "string data".to_owned());
476 // Not quite nondeterministic.
482 fn test_static_pointer() {
483 static key: Key<&'static int> = &Key;
484 static VALUE: int = 0;
485 let v: &'static int = &VALUE;
491 static key: Key<Box<int>> = &Key;
497 assert_eq!(**v.unwrap(), 1);
499 assert_eq!(**v.unwrap(), 1);
501 assert_eq!(**v.unwrap(), 1);
505 assert_eq!(**v.unwrap(), 2);
511 static key: Key<int> = &Key;
519 assert_eq!(*v.unwrap(), 2);
524 fn test_same_key_type() {
525 static key1: Key<int> = &Key;
526 static key2: Key<int> = &Key;
527 static key3: Key<int> = &Key;
528 static key4: Key<int> = &Key;
529 static key5: Key<int> = &Key;
536 get(key1, |x| assert_eq!(*x.unwrap(), 1));
537 get(key2, |x| assert_eq!(*x.unwrap(), 2));
538 get(key3, |x| assert_eq!(*x.unwrap(), 3));
539 get(key4, |x| assert_eq!(*x.unwrap(), 4));
540 get(key5, |x| assert_eq!(*x.unwrap(), 5));
545 fn test_nested_get_set1() {
546 static key: Key<int> = &Key;
555 fn test_nested_get_mut2() {
556 static key: Key<int> = &Key;
565 fn test_nested_get_mut3() {
566 static key: Key<int> = &Key;
575 fn test_nested_get_mut4() {
576 static key: Key<int> = &Key;