1 // Copyright 2014 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 use libc::types::os::arch::extra::{DWORD, LPVOID, BOOL};
18 use sys_common::mutex::{MUTEX_INIT, Mutex};
21 pub type Dtor = unsafe extern fn(*mut u8);
23 // Turns out, like pretty much everything, Windows is pretty close the
24 // functionality that Unix provides, but slightly different! In the case of
25 // TLS, Windows does not provide an API to provide a destructor for a TLS
26 // variable. This ends up being pretty crucial to this implementation, so we
27 // need a way around this.
29 // The solution here ended up being a little obscure, but fear not, the
30 // internet has informed me [1][2] that this solution is not unique (no way
31 // I could have thought of it as well!). The key idea is to insert some hook
32 // somewhere to run arbitrary code on thread termination. With this in place
33 // we'll be able to run anything we like, including all TLS destructors!
35 // To accomplish this feat, we perform a number of tasks, all contained
36 // within this module:
38 // * All TLS destructors are tracked by *us*, not the windows runtime. This
39 // means that we have a global list of destructors for each TLS key that
41 // * When a TLS key is destroyed, we're sure to remove it from the dtor list
43 // * When a thread exits, we run over the entire list and run dtors for all
44 // non-null keys. This attempts to match Unix semantics in this regard.
46 // This ends up having the overhead of using a global list, having some
47 // locks here and there, and in general just adding some more code bloat. We
48 // attempt to optimize runtime by forgetting keys that don't have
49 // destructors, but this only gets us so far.
51 // For more details and nitty-gritty, see the code sections below!
53 // [1]: http://www.codeproject.com/Articles/8113/Thread-Local-Storage-The-C-Way
54 // [2]: https://github.com/ChromiumWebApps/chromium/blob/master/base
55 // /threading/thread_local_storage_win.cc#L42
57 // NB these are specifically not types from `std::sync` as they currently rely
58 // on poisoning and this module needs to operate at a lower level than requiring
59 // the thread infrastructure to be in place (useful on the borders of
60 // initialization/destruction).
61 static DTOR_LOCK: Mutex = MUTEX_INIT;
62 static mut DTORS: *mut Vec<(Key, Dtor)> = 0 as *mut _;
64 // -------------------------------------------------------------------------
67 // This section is just raw bindings to the native functions that Windows
68 // provides, There's a few extra calls to deal with destructors.
71 pub unsafe fn create(dtor: Option<Dtor>) -> Key {
72 const TLS_OUT_OF_INDEXES: DWORD = 0xFFFFFFFF;
74 assert!(key != TLS_OUT_OF_INDEXES);
76 Some(f) => register_dtor(key, f),
83 pub unsafe fn set(key: Key, value: *mut u8) {
84 let r = TlsSetValue(key, value as LPVOID);
85 debug_assert!(r != 0);
89 pub unsafe fn get(key: Key) -> *mut u8 {
90 TlsGetValue(key) as *mut u8
94 pub unsafe fn destroy(key: Key) {
95 if unregister_dtor(key) {
96 // FIXME: Currently if a key has a destructor associated with it we
97 // can't actually ever unregister it. If we were to
98 // unregister it, then any key destruction would have to be
99 // serialized with respect to actually running destructors.
101 // We want to avoid a race where right before run_dtors runs
102 // some destructors TlsFree is called. Allowing the call to
103 // TlsFree would imply that the caller understands that *all
104 // known threads* are not exiting, which is quite a difficult
107 // For now we just leak all keys with dtors to "fix" this.
108 // Note that source [2] above shows precedent for this sort
111 let r = TlsFree(key);
112 debug_assert!(r != 0);
117 fn TlsAlloc() -> DWORD;
118 fn TlsFree(dwTlsIndex: DWORD) -> BOOL;
119 fn TlsGetValue(dwTlsIndex: DWORD) -> LPVOID;
120 fn TlsSetValue(dwTlsIndex: DWORD, lpTlsvalue: LPVOID) -> BOOL;
123 // -------------------------------------------------------------------------
126 // These functions are associated with registering and unregistering
127 // destructors. They're pretty simple, they just push onto a vector and scan
128 // a vector currently.
130 // FIXME: This could probably be at least a little faster with a BTree.
132 unsafe fn init_dtors() {
133 if !DTORS.is_null() { return }
135 let dtors = box Vec::<(Key, Dtor)>::new();
136 DTORS = mem::transmute(dtors);
141 DTORS = ptr::null_mut();
142 mem::transmute::<_, Box<Vec<(Key, Dtor)>>>(dtors);
143 assert!(DTORS.is_null()); // can't re-init after destructing
148 unsafe fn register_dtor(key: Key, dtor: Dtor) {
151 (*DTORS).push((key, dtor));
155 unsafe fn unregister_dtor(key: Key) -> bool {
159 let dtors = &mut *DTORS;
160 let before = dtors.len();
161 dtors.retain(|&(k, _)| k != key);
162 dtors.len() != before
168 // -------------------------------------------------------------------------
169 // Where the Magic (TM) Happens
171 // If you're looking at this code, and wondering "what is this doing?",
172 // you're not alone! I'll try to break this down step by step:
174 // # What's up with CRT$XLB?
176 // For anything about TLS destructors to work on Windows, we have to be able
177 // to run *something* when a thread exits. To do so, we place a very special
178 // static in a very special location. If this is encoded in just the right
179 // way, the kernel's loader is apparently nice enough to run some function
180 // of ours whenever a thread exits! How nice of the kernel!
182 // Lots of detailed information can be found in source [1] above, but the
183 // gist of it is that this is leveraging a feature of Microsoft's PE format
184 // (executable format) which is not actually used by any compilers today.
185 // This apparently translates to any callbacks in the ".CRT$XLB" section
186 // being run on certain events.
188 // So after all that, we use the compiler's #[link_section] feature to place
189 // a callback pointer into the magic section so it ends up being called.
191 // # What's up with this callback?
193 // The callback specified receives a number of parameters from... someone!
194 // (the kernel? the runtime? I'm not qute sure!) There are a few events that
195 // this gets invoked for, but we're currently only interested on when a
196 // thread or a process "detaches" (exits). The process part happens for the
197 // last thread and the thread part happens for any normal thread.
199 // # Ok, what's up with running all these destructors?
201 // This will likely need to be improved over time, but this function
202 // attempts a "poor man's" destructor callback system. To do this we clone a
203 // local copy of the dtor list to start out with. This is our fudgy attempt
204 // to not hold the lock while destructors run and not worry about the list
205 // changing while we're looking at it.
207 // Once we've got a list of what to run, we iterate over all keys, check
208 // their values, and then run destructors if the values turn out to be non
209 // null (setting them to null just beforehand). We do this a few times in a
210 // loop to basically match Unix semantics. If we don't reach a fixed point
211 // after a short while then we just inevitably leak something most likely.
213 // # The article mentions crazy stuff about "/INCLUDE"?
215 // It sure does! This seems to work for now, so maybe we'll just run into
216 // that if we start linking with msvc?
218 #[link_section = ".CRT$XLB"]
219 #[linkage = "external"]
221 pub static p_thread_callback: unsafe extern "system" fn(LPVOID, DWORD,
226 unsafe extern "system" fn on_tls_callback(h: LPVOID,
229 const DLL_THREAD_DETACH: DWORD = 3;
230 const DLL_PROCESS_DETACH: DWORD = 0;
231 if dwReason == DLL_THREAD_DETACH || dwReason == DLL_PROCESS_DETACH {
236 unsafe fn run_dtors() {
237 let mut any_run = true;
238 for _ in range(0, 5i) {
239 if !any_run { break }
243 let ret = if DTORS.is_null() {
246 (*DTORS).iter().map(|s| *s).collect()
251 for &(key, dtor) in dtors.iter() {
252 let ptr = TlsGetValue(key);
254 TlsSetValue(key, ptr::null_mut());