1 // Copyright 2012 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.
11 #[allow(missing_doc)];
21 use rt::task::{Task, LocalStorage};
24 NewHandle(*mut LocalStorage)
28 pub fn new() -> Handle {
31 let task = Local::unsafe_borrow::<Task>();
32 NewHandle(&mut (*task).storage)
39 NoLoan, ImmLoan, MutLoan
43 fn describe(&self) -> &'static str {
46 ImmLoan => "immutable",
53 impl<T: 'static> LocalData for T {}
55 // The task-local-map stores all TLS information for the currently running task.
56 // It is stored as an owned pointer into the runtime, and it's only allocated
57 // when TLS is used for the first time. This map must be very carefully
58 // constructed because it has many mutable loans unsoundly handed out on it to
59 // the various invocations of TLS requests.
61 // One of the most important operations is loaning a value via `get` to a
62 // caller. In doing so, the slot that the TLS entry is occupying cannot be
63 // invalidated because upon returning it's loan state must be updated. Currently
64 // the TLS map is a vector, but this is possibly dangerous because the vector
65 // can be reallocated/moved when new values are pushed onto it.
67 // This problem currently isn't solved in a very elegant way. Inside the `get`
68 // function, it internally "invalidates" all references after the loan is
69 // finished and looks up into the vector again. In theory this will prevent
70 // pointers from being moved under our feet so long as LLVM doesn't go too crazy
71 // with the optimizations.
73 // n.b. Other structures are not sufficient right now:
74 // * HashMap uses ~[T] internally (push reallocates/moves)
75 // * TreeMap is plausible, but it's in extra
76 // * dlist plausible, but not in std
77 // * a custom owned linked list was attempted, but difficult to write
78 // and involved a lot of extra code bloat
80 // n.b. Has to be stored with a pointer at outermost layer; the foreign call
83 // n.b. If TLS is used heavily in future, this could be made more efficient with
85 type TaskLocalMap = ~[Option<(*libc::c_void, TLSValue, LoanState)>];
86 type TLSValue = ~LocalData:;
88 fn cleanup_task_local_map(map_ptr: *libc::c_void) {
90 assert!(!map_ptr.is_null());
91 // Get and keep the single reference that was created at the
93 let _map: TaskLocalMap = cast::transmute(map_ptr);
94 // All local_data will be destroyed along with the map.
98 // Gets the map from the runtime. Lazily initialises if not done so already.
99 unsafe fn get_local_map(handle: Handle) -> &mut TaskLocalMap {
101 unsafe fn newsched_map(local: *mut LocalStorage) -> &mut TaskLocalMap {
102 // This is based on the same idea as the oldsched code above.
104 // If the at_exit function is already set, then we just need to take
105 // a loan out on the TLS map stored inside
106 &LocalStorage(ref mut map_ptr, Some(_)) => {
107 assert!(map_ptr.is_not_null());
108 return cast::transmute(map_ptr);
110 // If this is the first time we've accessed TLS, perform similar
111 // actions to the oldsched way of doing things.
112 &LocalStorage(ref mut map_ptr, ref mut at_exit) => {
113 assert!(map_ptr.is_null());
114 assert!(at_exit.is_none());
115 let map: TaskLocalMap = ~[];
116 *map_ptr = cast::transmute(map);
117 *at_exit = Some(cleanup_task_local_map);
118 return cast::transmute(map_ptr);
124 NewHandle(local_storage) => newsched_map(local_storage)
128 unsafe fn key_to_key_value<T: 'static>(key: local_data::Key<T>) -> *libc::c_void {
129 let pair: raw::Closure = cast::transmute_copy(&key);
130 return pair.code as *libc::c_void;
133 pub unsafe fn local_pop<T: 'static>(handle: Handle,
134 key: local_data::Key<T>) -> Option<T> {
135 let map = get_local_map(handle);
136 let key_value = key_to_key_value(key);
138 for entry in map.mut_iter() {
140 Some((k, _, loan)) if k == key_value => {
142 fail!("TLS value cannot be removed because it is already \
143 borrowed as %s", loan.describe());
145 // Move the data out of the `entry` slot via util::replace. This
146 // is guaranteed to succeed because we already matched on `Some`
148 let data = match util::replace(entry, None) {
149 Some((_, data, _)) => data,
150 None => libc::abort(),
153 // Move `data` into transmute to get out the memory that it
154 // owns, we must free it manually later.
155 let (_vtable, box): (uint, ~~T) = cast::transmute(data);
157 // Read the box's value (using the compiler's built-in
158 // auto-deref functionality to obtain a pointer to the base)
159 let ret = ptr::read_ptr(cast::transmute::<&T, *mut T>(*box));
161 // Finally free the allocated memory. we don't want this to
162 // actually touch the memory inside because it's all duplicated
163 // now, so the box is transmuted to a 0-sized type. We also use
164 // a type which references `T` because currently the layout
165 // could depend on whether T contains managed pointers or not.
166 let _: ~~[T, ..0] = cast::transmute(box);
168 // Everything is now deallocated, and we own the value that was
169 // located inside TLS, so we now return it.
178 pub unsafe fn local_get<T: 'static, U>(handle: Handle,
179 key: local_data::Key<T>,
180 f: &fn(Option<&T>) -> U) -> U {
181 local_get_with(handle, key, ImmLoan, f)
184 pub unsafe fn local_get_mut<T: 'static, U>(handle: Handle,
185 key: local_data::Key<T>,
186 f: &fn(Option<&mut T>) -> U) -> U {
187 do local_get_with(handle, key, MutLoan) |x| {
190 // We're violating a lot of compiler guarantees with this
191 // invocation of `transmute_mut`, but we're doing runtime checks to
192 // ensure that it's always valid (only one at a time).
194 // there is no need to be upset!
195 Some(x) => { f(Some(cast::transmute_mut(x))) }
200 unsafe fn local_get_with<T: 'static, U>(handle: Handle,
201 key: local_data::Key<T>,
203 f: &fn(Option<&T>) -> U) -> U {
204 // This function must be extremely careful. Because TLS can store owned
205 // values, and we must have some form of `get` function other than `pop`,
206 // this function has to give a `&` reference back to the caller.
208 // One option is to return the reference, but this cannot be sound because
209 // the actual lifetime of the object is not known. The slot in TLS could not
210 // be modified until the object goes out of scope, but the TLS code cannot
211 // know when this happens.
213 // For this reason, the reference is yielded to a specified closure. This
214 // way the TLS code knows exactly what the lifetime of the yielded pointer
215 // is, allowing callers to acquire references to owned data. This is also
216 // sound so long as measures are taken to ensure that while a TLS slot is
217 // loaned out to a caller, it's not modified recursively.
218 let map = get_local_map(handle);
219 let key_value = key_to_key_value(key);
221 let pos = map.iter().position(|entry| {
223 Some((k, _, _)) if k == key_value => true, _ => false
227 None => { return f(None); }
230 let mut return_loan = false;
232 Some((_, ref data, ref mut loan)) => {
233 match (state, *loan) {
238 (ImmLoan, ImmLoan) => {}
240 fail!("TLS slot cannot be borrowed as %s because \
241 it is already borrowed as %s",
242 want.describe(), cur.describe());
245 // data was created with `~~T as ~LocalData`, so we extract
246 // pointer part of the trait, (as ~~T), and then use
247 // compiler coercions to achieve a '&' pointer.
248 match *cast::transmute::<&TLSValue, &(uint, ~~T)>(data) {
249 (_vtable, ref box) => {
250 let value: &T = **box;
251 ret = f(Some(value));
258 // n.b. 'data' and 'loans' are both invalid pointers at the point
259 // 'f' returned because `f` could have appended more TLS items which
260 // in turn relocated the vector. Hence we do another lookup here to
264 Some((_, _, ref mut loan)) => { *loan = NoLoan; }
265 None => { libc::abort(); }
273 pub unsafe fn local_set<T: 'static>(handle: Handle,
274 key: local_data::Key<T>,
276 let map = get_local_map(handle);
277 let keyval = key_to_key_value(key);
279 // When the task-local map is destroyed, all the data needs to be cleaned
280 // up. For this reason we can't do some clever tricks to store '~T' as a
281 // '*c_void' or something like that. To solve the problem, we cast
282 // everything to a trait (LocalData) which is then stored inside the map.
283 // Upon destruction of the map, all the objects will be destroyed and the
284 // traits have enough information about them to destroy themselves.
286 // FIXME(#7673): This should be "~data as ~LocalData" (without the colon at
287 // the end, and only one sigil)
288 let data = ~~data as ~LocalData:;
290 fn insertion_position(map: &mut TaskLocalMap,
291 key: *libc::c_void) -> Option<uint> {
292 // First see if the map contains this key already
293 let curspot = map.iter().position(|entry| {
295 Some((ekey, _, loan)) if key == ekey => {
297 fail!("TLS value cannot be overwritten because it is
298 already borrowed as %s", loan.describe())
305 // If it doesn't contain the key, just find a slot that's None
308 None => map.iter().position(|entry| entry.is_none())
312 match insertion_position(map, keyval) {
313 Some(i) => { map[i] = Some((keyval, data, NoLoan)); }
314 None => { map.push(Some((keyval, data, NoLoan))); }