1 use crate::mem::ManuallyDrop;
3 use crate::sync::atomic::AtomicPtr;
4 use crate::sync::atomic::Ordering::SeqCst;
7 pub type Key = c::DWORD;
8 pub type Dtor = unsafe extern "C" fn(*mut u8);
10 // Turns out, like pretty much everything, Windows is pretty close the
11 // functionality that Unix provides, but slightly different! In the case of
12 // TLS, Windows does not provide an API to provide a destructor for a TLS
13 // variable. This ends up being pretty crucial to this implementation, so we
14 // need a way around this.
16 // The solution here ended up being a little obscure, but fear not, the
17 // internet has informed me [1][2] that this solution is not unique (no way
18 // I could have thought of it as well!). The key idea is to insert some hook
19 // somewhere to run arbitrary code on thread termination. With this in place
20 // we'll be able to run anything we like, including all TLS destructors!
22 // To accomplish this feat, we perform a number of threads, all contained
23 // within this module:
25 // * All TLS destructors are tracked by *us*, not the windows runtime. This
26 // means that we have a global list of destructors for each TLS key that
28 // * When a thread exits, we run over the entire list and run dtors for all
29 // non-null keys. This attempts to match Unix semantics in this regard.
31 // This ends up having the overhead of using a global list, having some
32 // locks here and there, and in general just adding some more code bloat. We
33 // attempt to optimize runtime by forgetting keys that don't have
34 // destructors, but this only gets us so far.
36 // For more details and nitty-gritty, see the code sections below!
38 // [1]: http://www.codeproject.com/Articles/8113/Thread-Local-Storage-The-C-Way
39 // [2]: https://github.com/ChromiumWebApps/chromium/blob/master/base
40 // /threading/thread_local_storage_win.cc#L42
42 // -------------------------------------------------------------------------
45 // This section is just raw bindings to the native functions that Windows
46 // provides, There's a few extra calls to deal with destructors.
49 pub unsafe fn create(dtor: Option<Dtor>) -> Key {
50 let key = c::TlsAlloc();
51 assert!(key != c::TLS_OUT_OF_INDEXES);
52 if let Some(f) = dtor {
53 register_dtor(key, f);
59 pub unsafe fn set(key: Key, value: *mut u8) {
60 let r = c::TlsSetValue(key, value as c::LPVOID);
61 debug_assert!(r != 0);
65 pub unsafe fn get(key: Key) -> *mut u8 {
66 c::TlsGetValue(key) as *mut u8
70 pub unsafe fn destroy(_key: Key) {
71 rtabort!("can't destroy tls keys on windows")
75 pub fn requires_synchronized_create() -> bool {
79 // -------------------------------------------------------------------------
82 // Windows has no native support for running destructors so we manage our own
83 // list of destructors to keep track of how to destroy keys. We then install a
84 // callback later to get invoked whenever a thread exits, running all
85 // appropriate destructors.
87 // Currently unregistration from this list is not supported. A destructor can be
88 // registered but cannot be unregistered. There's various simplifying reasons
89 // for doing this, the big ones being:
91 // 1. Currently we don't even support deallocating TLS keys, so normal operation
92 // doesn't need to deallocate a destructor.
93 // 2. There is no point in time where we know we can unregister a destructor
94 // because it could always be getting run by some remote thread.
96 // Typically processes have a statically known set of TLS keys which is pretty
97 // small, and we'd want to keep this memory alive for the whole process anyway
100 // Perhaps one day we can fold the `Box` here into a static allocation,
101 // expanding the `StaticKey` structure to contain not only a slot for the TLS
102 // key but also a slot for the destructor queue on windows. An optimization for
105 static DTORS: AtomicPtr<Node> = AtomicPtr::new(ptr::null_mut());
113 unsafe fn register_dtor(key: Key, dtor: Dtor) {
114 let mut node = ManuallyDrop::new(Box::new(Node { key, dtor, next: ptr::null_mut() }));
116 let mut head = DTORS.load(SeqCst);
119 match DTORS.compare_exchange(head, &mut **node, SeqCst, SeqCst) {
120 Ok(_) => return, // nothing to drop, we successfully added the node to the list
121 Err(cur) => head = cur,
126 // -------------------------------------------------------------------------
127 // Where the Magic (TM) Happens
129 // If you're looking at this code, and wondering "what is this doing?",
130 // you're not alone! I'll try to break this down step by step:
132 // # What's up with CRT$XLB?
134 // For anything about TLS destructors to work on Windows, we have to be able
135 // to run *something* when a thread exits. To do so, we place a very special
136 // static in a very special location. If this is encoded in just the right
137 // way, the kernel's loader is apparently nice enough to run some function
138 // of ours whenever a thread exits! How nice of the kernel!
140 // Lots of detailed information can be found in source [1] above, but the
141 // gist of it is that this is leveraging a feature of Microsoft's PE format
142 // (executable format) which is not actually used by any compilers today.
143 // This apparently translates to any callbacks in the ".CRT$XLB" section
144 // being run on certain events.
146 // So after all that, we use the compiler's #[link_section] feature to place
147 // a callback pointer into the magic section so it ends up being called.
149 // # What's up with this callback?
151 // The callback specified receives a number of parameters from... someone!
152 // (the kernel? the runtime? I'm not quite sure!) There are a few events that
153 // this gets invoked for, but we're currently only interested on when a
154 // thread or a process "detaches" (exits). The process part happens for the
155 // last thread and the thread part happens for any normal thread.
157 // # Ok, what's up with running all these destructors?
159 // This will likely need to be improved over time, but this function
160 // attempts a "poor man's" destructor callback system. Once we've got a list
161 // of what to run, we iterate over all keys, check their values, and then run
162 // destructors if the values turn out to be non null (setting them to null just
163 // beforehand). We do this a few times in a loop to basically match Unix
164 // semantics. If we don't reach a fixed point after a short while then we just
165 // inevitably leak something most likely.
167 // # The article mentions weird stuff about "/INCLUDE"?
169 // It sure does! Specifically we're talking about this quote:
171 // The Microsoft run-time library facilitates this process by defining a
172 // memory image of the TLS Directory and giving it the special name
173 // “__tls_used” (Intel x86 platforms) or “_tls_used” (other platforms). The
174 // linker looks for this memory image and uses the data there to create the
175 // TLS Directory. Other compilers that support TLS and work with the
176 // Microsoft linker must use this same technique.
178 // Basically what this means is that if we want support for our TLS
179 // destructors/our hook being called then we need to make sure the linker does
180 // not omit this symbol. Otherwise it will omit it and our callback won't be
183 // We don't actually use the `/INCLUDE` linker flag here like the article
184 // mentions because the Rust compiler doesn't propagate linker flags, but
185 // instead we use a shim function which performs a volatile 1-byte load from
186 // the address of the symbol to ensure it sticks around.
188 #[link_section = ".CRT$XLB"]
189 #[allow(dead_code, unused_variables)]
190 #[used] // we don't want LLVM eliminating this symbol for any reason, and
191 // when the symbol makes it to the linker the linker will take over
192 pub static p_thread_callback: unsafe extern "system" fn(c::LPVOID, c::DWORD, c::LPVOID) =
195 #[allow(dead_code, unused_variables)]
196 unsafe extern "system" fn on_tls_callback(h: c::LPVOID, dwReason: c::DWORD, pv: c::LPVOID) {
197 if dwReason == c::DLL_THREAD_DETACH || dwReason == c::DLL_PROCESS_DETACH {
201 // See comments above for what this is doing. Note that we don't need this
202 // trickery on GNU windows, just on MSVC.
203 reference_tls_used();
204 #[cfg(target_env = "msvc")]
205 unsafe fn reference_tls_used() {
207 static _tls_used: u8;
209 crate::intrinsics::volatile_load(&_tls_used);
211 #[cfg(not(target_env = "msvc"))]
212 unsafe fn reference_tls_used() {}
215 #[allow(dead_code)] // actually called above
216 unsafe fn run_dtors() {
217 let mut any_run = true;
223 let mut cur = DTORS.load(SeqCst);
224 while !cur.is_null() {
225 let ptr = c::TlsGetValue((*cur).key);
228 c::TlsSetValue((*cur).key, ptr::null_mut());
229 ((*cur).dtor)(ptr as *mut _);