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 apppriately
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, Some(&3)));
34 local_data::set(key_vector, ~[4]);
35 local_data::get(key_vector, |opt| assert_eq!(opt, Some(&~[4])));
40 // Casting 'Arcane Sight' reveals an overwhelming aura of Transmutation
46 use rt::task::{Task, LocalStorage};
50 * Indexes a task-local data slot. This pointer is used for comparison to
51 * differentiate keys from one another. The actual type `T` is not used anywhere
52 * as a member of this type, except that it is parameterized with it to define
53 * the type of each key's value.
55 * The value of each Key is of the singleton enum KeyValue. These also have the
56 * same name as `Key` and their purpose is to take up space in the programs data
57 * sections to ensure that each value of the `Key` type points to a unique
60 pub type Key<T> = &'static KeyValue<T>;
62 pub enum KeyValue<T> { Key }
65 impl<T: 'static> LocalData for T {}
67 // The task-local-map stores all TLS information for the currently running task.
68 // It is stored as an owned pointer into the runtime, and it's only allocated
69 // when TLS is used for the first time. This map must be very carefully
70 // constructed because it has many mutable loans unsoundly handed out on it to
71 // the various invocations of TLS requests.
73 // One of the most important operations is loaning a value via `get` to a
74 // caller. In doing so, the slot that the TLS entry is occupying cannot be
75 // invalidated because upon returning it's loan state must be updated. Currently
76 // the TLS map is a vector, but this is possibly dangerous because the vector
77 // can be reallocated/moved when new values are pushed onto it.
79 // This problem currently isn't solved in a very elegant way. Inside the `get`
80 // function, it internally "invalidates" all references after the loan is
81 // finished and looks up into the vector again. In theory this will prevent
82 // pointers from being moved under our feet so long as LLVM doesn't go too crazy
83 // with the optimizations.
85 // n.b. If TLS is used heavily in future, this could be made more efficient with
88 pub type Map = ~[Option<(*libc::c_void, TLSValue, LoanState)>];
89 type TLSValue = ~LocalData;
91 // Gets the map from the runtime. Lazily initialises if not done so already.
92 unsafe fn get_local_map() -> &mut Map {
95 let task: *mut Task = Local::unsafe_borrow();
96 match &mut (*task).storage {
97 // If the at_exit function is already set, then we just need to take
98 // a loan out on the TLS map stored inside
99 &LocalStorage(Some(ref mut map_ptr)) => {
102 // If this is the first time we've accessed TLS, perform similar
103 // actions to the oldsched way of doing things.
104 &LocalStorage(ref mut slot) => {
107 Some(ref mut map_ptr) => { return map_ptr }
116 NoLoan, ImmLoan, MutLoan
120 fn describe(&self) -> &'static str {
123 ImmLoan => "immutable",
129 fn key_to_key_value<T: 'static>(key: Key<T>) -> *libc::c_void {
130 unsafe { cast::transmute(key) }
133 /// Removes a task-local value from task-local storage. This will return
134 /// Some(value) if the key was present in TLS, otherwise it will return None.
136 /// A runtime assertion will be triggered it removal of TLS value is attempted
137 /// while the value is still loaned out via `get` or `get_mut`.
138 pub fn pop<T: 'static>(key: Key<T>) -> Option<T> {
139 let map = unsafe { get_local_map() };
140 let key_value = key_to_key_value(key);
142 for entry in map.mut_iter() {
144 Some((k, _, loan)) if k == key_value => {
146 fail!("TLS value cannot be removed because it is currently \
147 borrowed as %s", loan.describe());
149 // Move the data out of the `entry` slot via util::replace.
150 // This is guaranteed to succeed because we already matched
152 let data = match util::replace(entry, None) {
153 Some((_, data, _)) => data,
157 // Move `data` into transmute to get out the memory that it
158 // owns, we must free it manually later.
159 let (_vtable, box): (uint, ~T) = unsafe {
160 cast::transmute(data)
163 // Now that we own `box`, we can just move out of it as we would
164 // with any other data.
173 /// Retrieves a value from TLS. The closure provided is yielded `Some` of a
174 /// reference to the value located in TLS if one exists, or `None` if the key
175 /// provided is not present in TLS currently.
177 /// It is considered a runtime error to attempt to get a value which is already
178 /// on loan via the `get_mut` method provided.
179 pub fn get<T: 'static, U>(key: Key<T>, f: &fn(Option<&T>) -> U) -> U {
180 get_with(key, ImmLoan, f)
183 /// Retrieves a mutable value from TLS. The closure provided is yielded `Some`
184 /// of a reference to the mutable value located in TLS if one exists, or `None`
185 /// if the key provided is not present in TLS currently.
187 /// It is considered a runtime error to attempt to get a value which is already
188 /// on loan via this or the `get` methods. This is similar to how it's a runtime
189 /// error to take two mutable loans on an `@mut` box.
190 pub fn get_mut<T: 'static, U>(key: Key<T>, f: &fn(Option<&mut T>) -> U) -> U {
191 do get_with(key, MutLoan) |x| {
194 // We're violating a lot of compiler guarantees with this
195 // invocation of `transmute_mut`, but we're doing runtime checks to
196 // ensure that it's always valid (only one at a time).
198 // there is no need to be upset!
199 Some(x) => { f(Some(unsafe { cast::transmute_mut(x) })) }
204 fn get_with<T: 'static, U>(key: Key<T>,
206 f: &fn(Option<&T>) -> U) -> U {
207 // This function must be extremely careful. Because TLS can store owned
208 // values, and we must have some form of `get` function other than `pop`,
209 // this function has to give a `&` reference back to the caller.
211 // One option is to return the reference, but this cannot be sound because
212 // the actual lifetime of the object is not known. The slot in TLS could not
213 // be modified until the object goes out of scope, but the TLS code cannot
214 // know when this happens.
216 // For this reason, the reference is yielded to a specified closure. This
217 // way the TLS code knows exactly what the lifetime of the yielded pointer
218 // is, allowing callers to acquire references to owned data. This is also
219 // sound so long as measures are taken to ensure that while a TLS slot is
220 // loaned out to a caller, it's not modified recursively.
221 let map = unsafe { get_local_map() };
222 let key_value = key_to_key_value(key);
224 let pos = map.iter().position(|entry| {
226 Some((k, _, _)) if k == key_value => true, _ => false
230 None => { return f(None); }
233 let mut return_loan = false;
235 Some((_, ref data, ref mut loan)) => {
236 match (state, *loan) {
241 (ImmLoan, ImmLoan) => {}
243 fail!("TLS slot cannot be borrowed as %s because \
244 it is already borrowed as %s",
245 want.describe(), cur.describe());
248 // data was created with `~T as ~LocalData`, so we extract
249 // pointer part of the trait, (as ~T), and then use
250 // compiler coercions to achieve a '&' pointer.
252 match *cast::transmute::<&TLSValue, &(uint, ~T)>(data){
253 (_vtable, ref box) => {
254 let value: &T = *box;
255 ret = f(Some(value));
263 // n.b. 'data' and 'loans' are both invalid pointers at the point
264 // 'f' returned because `f` could have appended more TLS items which
265 // in turn relocated the vector. Hence we do another lookup here to
269 Some((_, _, ref mut loan)) => { *loan = NoLoan; }
279 #[fixed_stack_segment]; #[inline(never)];
280 unsafe { libc::abort() }
283 /// Inserts a value into task local storage. If the key is already present in
284 /// TLS, then the previous value is removed and replaced with the provided data.
286 /// It is considered a runtime error to attempt to set a key which is currently
287 /// on loan via the `get` or `get_mut` methods.
288 pub fn set<T: 'static>(key: Key<T>, data: T) {
289 let map = unsafe { get_local_map() };
290 let keyval = key_to_key_value(key);
292 // When the task-local map is destroyed, all the data needs to be cleaned
293 // up. For this reason we can't do some clever tricks to store '~T' as a
294 // '*c_void' or something like that. To solve the problem, we cast
295 // everything to a trait (LocalData) which is then stored inside the map.
296 // Upon destruction of the map, all the objects will be destroyed and the
297 // traits have enough information about them to destroy themselves.
298 let data = ~data as ~LocalData:;
300 fn insertion_position(map: &mut Map,
301 key: *libc::c_void) -> Option<uint> {
302 // First see if the map contains this key already
303 let curspot = map.iter().position(|entry| {
305 Some((ekey, _, loan)) if key == ekey => {
307 fail!("TLS value cannot be overwritten because it is
308 already borrowed as %s", loan.describe())
315 // If it doesn't contain the key, just find a slot that's None
318 None => map.iter().position(|entry| entry.is_none())
322 // The type of the local data map must ascribe to Send, so we do the
323 // transmute here to add the Send bound back on. This doesn't actually
324 // matter because TLS will always own the data (until its moved out) and
325 // we're not actually sending it to other schedulers or anything.
326 let data: ~LocalData = unsafe { cast::transmute(data) };
327 match insertion_position(map, keyval) {
328 Some(i) => { map[i] = Some((keyval, data, NoLoan)); }
329 None => { map.push(Some((keyval, data, NoLoan))); }
333 /// Modifies a task-local value by temporarily removing it from task-local
334 /// storage and then re-inserting if `Some` is returned from the closure.
336 /// This function will have the same runtime errors as generated from `pop` and
337 /// `set` (the key must not currently be on loan
338 pub fn modify<T: 'static>(key: Key<T>, f: &fn(Option<T>) -> Option<T>) {
340 Some(next) => { set(key, next); }
352 fn test_tls_multitask() {
353 static my_key: Key<@~str> = &Key;
354 set(my_key, @~"parent data");
356 // TLS shouldn't carry over.
357 assert!(get(my_key, |k| k.map_move(|k| *k)).is_none());
358 set(my_key, @~"child data");
359 assert!(*(get(my_key, |k| k.map_move(|k| *k)).unwrap()) ==
361 // should be cleaned up for us
363 // Must work multiple times
364 assert!(*(get(my_key, |k| k.map_move(|k| *k)).unwrap()) == ~"parent data");
365 assert!(*(get(my_key, |k| k.map_move(|k| *k)).unwrap()) == ~"parent data");
366 assert!(*(get(my_key, |k| k.map_move(|k| *k)).unwrap()) == ~"parent data");
370 fn test_tls_overwrite() {
371 static my_key: Key<@~str> = &Key;
372 set(my_key, @~"first data");
373 set(my_key, @~"next data"); // Shouldn't leak.
374 assert!(*(get(my_key, |k| k.map_move(|k| *k)).unwrap()) == ~"next data");
379 static my_key: Key<@~str> = &Key;
380 set(my_key, @~"weasel");
381 assert!(*(pop(my_key).unwrap()) == ~"weasel");
382 // Pop must remove the data from the map.
383 assert!(pop(my_key).is_none());
387 fn test_tls_modify() {
388 static my_key: Key<@~str> = &Key;
389 modify(my_key, |data| {
391 Some(@ref val) => fail!("unwelcome value: %s", *val),
392 None => Some(@~"first data")
395 modify(my_key, |data| {
397 Some(@~"first data") => Some(@~"next data"),
398 Some(@ref val) => fail!("wrong value: %s", *val),
399 None => fail!("missing value")
402 assert!(*(pop(my_key).unwrap()) == ~"next data");
406 fn test_tls_crust_automorestack_memorial_bug() {
407 // This might result in a stack-canary clobber if the runtime fails to
408 // set sp_limit to 0 when calling the cleanup extern - it might
409 // automatically jump over to the rust stack, which causes next_c_sp
410 // to get recorded as something within a rust stack segment. Then a
411 // subsequent upcall (esp. for logging, think vsnprintf) would run on
412 // a stack smaller than 1 MB.
413 static my_key: Key<@~str> = &Key;
415 set(my_key, @~"hax");
420 fn test_tls_multiple_types() {
421 static str_key: Key<@~str> = &Key;
422 static box_key: Key<@@()> = &Key;
423 static int_key: Key<@int> = &Key;
425 set(str_key, @~"string data");
432 fn test_tls_overwrite_multiple_types() {
433 static str_key: Key<@~str> = &Key;
434 static box_key: Key<@@()> = &Key;
435 static int_key: Key<@int> = &Key;
437 set(str_key, @~"string data");
439 // This could cause a segfault if overwriting-destruction is done
440 // with the crazy polymorphic transmute rather than the provided
442 set(int_key, @31337);
448 fn test_tls_cleanup_on_failure() {
449 static str_key: Key<@~str> = &Key;
450 static box_key: Key<@@()> = &Key;
451 static int_key: Key<@int> = &Key;
452 set(str_key, @~"parent data");
456 set(str_key, @~"string data");
461 // Not quite nondeterministic.
462 set(int_key, @31337);
467 fn test_static_pointer() {
468 static key: Key<@&'static int> = &Key;
469 static VALUE: int = 0;
470 let v: @&'static int = @&VALUE;
476 static key: Key<~int> = &Key;
482 assert_eq!(**v.unwrap(), 1);
484 assert_eq!(**v.unwrap(), 1);
486 assert_eq!(**v.unwrap(), 1);
490 assert_eq!(**v.unwrap(), 2);
496 static key: Key<int> = &Key;
499 do get_mut(key) |v| {
504 assert_eq!(*v.unwrap(), 2);
509 fn test_same_key_type() {
510 static key1: Key<int> = &Key;
511 static key2: Key<int> = &Key;
512 static key3: Key<int> = &Key;
513 static key4: Key<int> = &Key;
514 static key5: Key<int> = &Key;
521 get(key1, |x| assert_eq!(*x.unwrap(), 1));
522 get(key2, |x| assert_eq!(*x.unwrap(), 2));
523 get(key3, |x| assert_eq!(*x.unwrap(), 3));
524 get(key4, |x| assert_eq!(*x.unwrap(), 4));
525 get(key5, |x| assert_eq!(*x.unwrap(), 5));
530 fn test_nested_get_set1() {
531 static key: Key<int> = &Key;
540 fn test_nested_get_mut2() {
541 static key: Key<int> = &Key;
550 fn test_nested_get_mut3() {
551 static key: Key<int> = &Key;
553 do get_mut(key) |_| {
560 fn test_nested_get_mut4() {
561 static key: Key<int> = &Key;
563 do get_mut(key) |_| {