1 //! Implements threads.
3 use std::cell::RefCell;
4 use std::collections::hash_map::Entry;
5 use std::convert::TryFrom;
6 use std::num::TryFromIntError;
7 use std::time::{Duration, Instant, SystemTime};
11 use rustc_data_structures::fx::FxHashMap;
12 use rustc_hir::def_id::DefId;
13 use rustc_index::vec::{Idx, IndexVec};
15 use crate::sync::SynchronizationState;
18 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
19 pub enum SchedulingAction {
20 /// Execute step on the active thread.
22 /// Execute a timeout callback.
23 ExecuteTimeoutCallback,
24 /// Execute destructors of the active thread.
30 /// Timeout callbacks can be created by synchronization primitives to tell the
31 /// scheduler that they should be called once some period of time passes.
32 type TimeoutCallback<'mir, 'tcx> =
33 Box<dyn FnOnce(&mut InterpCx<'mir, 'tcx, Evaluator<'mir, 'tcx>>) -> InterpResult<'tcx> + 'tcx>;
35 /// A thread identifier.
36 #[derive(Clone, Copy, Debug, PartialOrd, Ord, PartialEq, Eq, Hash)]
37 pub struct ThreadId(u32);
39 /// The main thread. When it terminates, the whole application terminates.
40 const MAIN_THREAD: ThreadId = ThreadId(0);
43 pub fn to_u32(self) -> u32 {
48 impl Idx for ThreadId {
49 fn new(idx: usize) -> Self {
50 ThreadId(u32::try_from(idx).unwrap())
53 fn index(self) -> usize {
54 usize::try_from(self.0).unwrap()
58 impl TryFrom<u64> for ThreadId {
59 type Error = TryFromIntError;
60 fn try_from(id: u64) -> Result<Self, Self::Error> {
61 u32::try_from(id).map(|id_u32| Self(id_u32))
65 impl From<u32> for ThreadId {
66 fn from(id: u32) -> Self {
72 pub fn to_u32_scalar<'tcx>(&self) -> Scalar<Tag> {
73 Scalar::from_u32(u32::try_from(self.0).unwrap())
77 /// The state of a thread.
78 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
79 pub enum ThreadState {
80 /// The thread is enabled and can be executed.
82 /// The thread tried to join the specified thread and is blocked until that
83 /// thread terminates.
84 BlockedOnJoin(ThreadId),
85 /// The thread is blocked on some synchronization primitive. It is the
86 /// responsibility of the synchronization primitives to track threads that
87 /// are blocked by them.
89 /// The thread has terminated its execution. We do not delete terminated
90 /// threads (FIXME: why?).
94 /// The join status of a thread.
95 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
96 enum ThreadJoinStatus {
97 /// The thread can be joined.
99 /// A thread is detached if its join handle was destroyed and no other
100 /// thread can join it.
102 /// The thread was already joined by some thread and cannot be joined again.
107 pub struct Thread<'mir, 'tcx> {
110 /// Name of the thread.
111 thread_name: Option<Vec<u8>>,
113 /// The virtual call stack.
114 stack: Vec<Frame<'mir, 'tcx, Tag, FrameData<'tcx>>>,
117 join_status: ThreadJoinStatus,
119 /// The temporary used for storing the argument of
120 /// the call to `miri_start_panic` (the panic payload) when unwinding.
121 /// This is pointer-sized, and matches the `Payload` type in `src/libpanic_unwind/miri.rs`.
122 pub(crate) panic_payload: Option<Scalar<Tag>>,
124 /// Last OS error location in memory. It is a 32-bit integer.
125 pub(crate) last_error: Option<MPlaceTy<'tcx, Tag>>,
128 impl<'mir, 'tcx> Thread<'mir, 'tcx> {
129 /// Check if the thread is done executing (no more stack frames). If yes,
130 /// change the state to terminated and return `true`.
131 fn check_terminated(&mut self) -> bool {
132 if self.state == ThreadState::Enabled {
133 if self.stack.is_empty() {
134 self.state = ThreadState::Terminated;
141 /// Get the name of the current thread, or `<unnamed>` if it was not set.
142 fn thread_name(&self) -> &[u8] {
143 if let Some(ref thread_name) = self.thread_name {
151 impl<'mir, 'tcx> std::fmt::Debug for Thread<'mir, 'tcx> {
152 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
153 write!(f, "{}({:?}, {:?})", String::from_utf8_lossy(self.thread_name()), self.state, self.join_status)
157 impl<'mir, 'tcx> Default for Thread<'mir, 'tcx> {
158 fn default() -> Self {
160 state: ThreadState::Enabled,
163 join_status: ThreadJoinStatus::Joinable,
170 /// A specific moment in time.
174 RealTime(SystemTime),
178 /// How long do we have to wait from now until the specified time?
179 fn get_wait_time(&self) -> Duration {
181 Time::Monotonic(instant) => instant.saturating_duration_since(Instant::now()),
182 Time::RealTime(time) =>
183 time.duration_since(SystemTime::now()).unwrap_or(Duration::new(0, 0)),
188 /// Callbacks are used to implement timeouts. For example, waiting on a
189 /// conditional variable with a timeout creates a callback that is called after
190 /// the specified time and unblocks the thread. If another thread signals on the
191 /// conditional variable, the signal handler deletes the callback.
192 struct TimeoutCallbackInfo<'mir, 'tcx> {
193 /// The callback should be called no earlier than this time.
195 /// The called function.
196 callback: TimeoutCallback<'mir, 'tcx>,
199 impl<'mir, 'tcx> std::fmt::Debug for TimeoutCallbackInfo<'mir, 'tcx> {
200 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
201 write!(f, "TimeoutCallback({:?})", self.call_time)
205 /// A set of threads.
207 pub struct ThreadManager<'mir, 'tcx> {
208 /// Identifier of the currently active thread.
209 active_thread: ThreadId,
210 /// Threads used in the program.
212 /// Note that this vector also contains terminated threads.
213 threads: IndexVec<ThreadId, Thread<'mir, 'tcx>>,
214 /// This field is pub(crate) because the synchronization primitives
215 /// (`crate::sync`) need a way to access it.
216 pub(crate) sync: SynchronizationState,
217 /// A mapping from a thread-local static to an allocation id of a thread
218 /// specific allocation.
219 thread_local_alloc_ids: RefCell<FxHashMap<(DefId, ThreadId), AllocId>>,
220 /// A flag that indicates that we should change the active thread.
221 yield_active_thread: bool,
222 /// Callbacks that are called once the specified time passes.
223 timeout_callbacks: FxHashMap<ThreadId, TimeoutCallbackInfo<'mir, 'tcx>>,
226 impl<'mir, 'tcx> Default for ThreadManager<'mir, 'tcx> {
227 fn default() -> Self {
228 let mut threads = IndexVec::new();
229 // Create the main thread and add it to the list of threads.
230 let mut main_thread = Thread::default();
231 // The main thread can *not* be joined on.
232 main_thread.join_status = ThreadJoinStatus::Detached;
233 threads.push(main_thread);
235 active_thread: ThreadId::new(0),
237 sync: SynchronizationState::default(),
238 thread_local_alloc_ids: Default::default(),
239 yield_active_thread: false,
240 timeout_callbacks: FxHashMap::default(),
245 impl<'mir, 'tcx: 'mir> ThreadManager<'mir, 'tcx> {
246 /// Check if we have an allocation for the given thread local static for the
248 fn get_thread_local_alloc_id(&self, def_id: DefId) -> Option<AllocId> {
249 self.thread_local_alloc_ids.borrow().get(&(def_id, self.active_thread)).cloned()
252 /// Set the allocation id as the allocation id of the given thread local
253 /// static for the active thread.
255 /// Panics if a thread local is initialized twice for the same thread.
256 fn set_thread_local_alloc_id(&self, def_id: DefId, new_alloc_id: AllocId) {
257 self.thread_local_alloc_ids
259 .insert((def_id, self.active_thread), new_alloc_id)
263 /// Borrow the stack of the active thread.
264 fn active_thread_stack(&self) -> &[Frame<'mir, 'tcx, Tag, FrameData<'tcx>>] {
265 &self.threads[self.active_thread].stack
268 /// Mutably borrow the stack of the active thread.
269 fn active_thread_stack_mut(&mut self) -> &mut Vec<Frame<'mir, 'tcx, Tag, FrameData<'tcx>>> {
270 &mut self.threads[self.active_thread].stack
273 /// Create a new thread and returns its id.
274 fn create_thread(&mut self) -> ThreadId {
275 let new_thread_id = ThreadId::new(self.threads.len());
276 self.threads.push(Default::default());
280 /// Set an active thread and return the id of the thread that was active before.
281 fn set_active_thread_id(&mut self, id: ThreadId) -> ThreadId {
282 let active_thread_id = self.active_thread;
283 self.active_thread = id;
284 assert!(self.active_thread.index() < self.threads.len());
288 /// Get the id of the currently active thread.
289 fn get_active_thread_id(&self) -> ThreadId {
293 /// Get the total number of threads that were ever spawn by this program.
294 fn get_total_thread_count(&self) -> usize {
298 /// Has the given thread terminated?
299 fn has_terminated(&self, thread_id: ThreadId) -> bool {
300 self.threads[thread_id].state == ThreadState::Terminated
303 /// Enable the thread for execution. The thread must be terminated.
304 fn enable_thread(&mut self, thread_id: ThreadId) {
305 assert!(self.has_terminated(thread_id));
306 self.threads[thread_id].state = ThreadState::Enabled;
309 /// Get a mutable borrow of the currently active thread.
310 fn active_thread_mut(&mut self) -> &mut Thread<'mir, 'tcx> {
311 &mut self.threads[self.active_thread]
314 /// Get a shared borrow of the currently active thread.
315 fn active_thread_ref(&self) -> &Thread<'mir, 'tcx> {
316 &self.threads[self.active_thread]
319 /// Mark the thread as detached, which means that no other thread will try
320 /// to join it and the thread is responsible for cleaning up.
321 fn detach_thread(&mut self, id: ThreadId) -> InterpResult<'tcx> {
322 if self.threads[id].join_status != ThreadJoinStatus::Joinable {
323 throw_ub_format!("trying to detach thread that was already detached or joined");
325 self.threads[id].join_status = ThreadJoinStatus::Detached;
329 /// Mark that the active thread tries to join the thread with `joined_thread_id`.
330 fn join_thread(&mut self, joined_thread_id: ThreadId) -> InterpResult<'tcx> {
331 if self.threads[joined_thread_id].join_status != ThreadJoinStatus::Joinable {
332 throw_ub_format!("trying to join a detached or already joined thread");
334 if joined_thread_id == self.active_thread {
335 throw_ub_format!("trying to join itself");
340 .all(|thread| thread.state != ThreadState::BlockedOnJoin(joined_thread_id)),
341 "a joinable thread already has threads waiting for its termination"
343 // Mark the joined thread as being joined so that we detect if other
344 // threads try to join it.
345 self.threads[joined_thread_id].join_status = ThreadJoinStatus::Joined;
346 if self.threads[joined_thread_id].state != ThreadState::Terminated {
347 // The joined thread is still running, we need to wait for it.
348 self.active_thread_mut().state = ThreadState::BlockedOnJoin(joined_thread_id);
350 "{:?} blocked on {:?} when trying to join",
358 /// Set the name of the active thread.
359 fn set_thread_name(&mut self, new_thread_name: Vec<u8>) {
360 self.active_thread_mut().thread_name = Some(new_thread_name);
363 /// Get the name of the active thread.
364 fn get_thread_name(&self) -> &[u8] {
365 self.active_thread_ref().thread_name()
368 /// Put the thread into the blocked state.
369 fn block_thread(&mut self, thread: ThreadId) {
370 let state = &mut self.threads[thread].state;
371 assert_eq!(*state, ThreadState::Enabled);
372 *state = ThreadState::BlockedOnSync;
375 /// Put the blocked thread into the enabled state.
376 fn unblock_thread(&mut self, thread: ThreadId) {
377 let state = &mut self.threads[thread].state;
378 assert_eq!(*state, ThreadState::BlockedOnSync);
379 *state = ThreadState::Enabled;
382 /// Change the active thread to some enabled thread.
383 fn yield_active_thread(&mut self) {
384 // We do not yield immediately, as swapping out the current stack while executing a MIR statement
385 // could lead to all sorts of confusion.
386 // We should only switch stacks between steps.
387 self.yield_active_thread = true;
390 /// Register the given `callback` to be called once the `call_time` passes.
392 /// The callback will be called with `thread` being the active thread, and
393 /// the callback may not change the active thread.
394 fn register_timeout_callback(
398 callback: TimeoutCallback<'mir, 'tcx>,
400 self.timeout_callbacks
401 .insert(thread, TimeoutCallbackInfo { call_time, callback })
405 /// Unregister the callback for the `thread`.
406 fn unregister_timeout_callback_if_exists(&mut self, thread: ThreadId) {
407 self.timeout_callbacks.remove(&thread);
410 /// Get a callback that is ready to be called.
411 fn get_ready_callback(&mut self) -> Option<(ThreadId, TimeoutCallback<'mir, 'tcx>)> {
412 // We iterate over all threads in the order of their indices because
413 // this allows us to have a deterministic scheduler.
414 for thread in self.threads.indices() {
415 match self.timeout_callbacks.entry(thread) {
416 Entry::Occupied(entry) =>
417 if entry.get().call_time.get_wait_time() == Duration::new(0, 0) {
418 return Some((thread, entry.remove().callback));
420 Entry::Vacant(_) => {}
426 /// Wakes up threads joining on the active one and deallocates thread-local statics.
427 /// The `AllocId` that can now be freed is returned.
428 fn thread_terminated(&mut self) -> Vec<AllocId> {
429 let mut free_tls_statics = Vec::new();
431 let mut thread_local_statics = self.thread_local_alloc_ids.borrow_mut();
432 thread_local_statics.retain(|&(_def_id, thread), &mut alloc_id| {
433 if thread != self.active_thread {
434 // Keep this static around.
437 // Delete this static from the map and from memory.
438 // We cannot free directly here as we cannot use `?` in this context.
439 free_tls_statics.push(alloc_id);
443 // Check if we need to unblock any threads.
444 for (i, thread) in self.threads.iter_enumerated_mut() {
445 if thread.state == ThreadState::BlockedOnJoin(self.active_thread) {
446 trace!("unblocking {:?} because {:?} terminated", i, self.active_thread);
447 thread.state = ThreadState::Enabled;
450 return free_tls_statics;
453 /// Decide which action to take next and on which thread.
455 /// The currently implemented scheduling policy is the one that is commonly
456 /// used in stateless model checkers such as Loom: run the active thread as
457 /// long as we can and switch only when we have to (the active thread was
458 /// blocked, terminated, or has explicitly asked to be preempted).
459 fn schedule(&mut self) -> InterpResult<'tcx, SchedulingAction> {
460 // Check whether the thread has **just** terminated (`check_terminated`
461 // checks whether the thread has popped all its stack and if yes, sets
462 // the thread state to terminated).
463 if self.threads[self.active_thread].check_terminated() {
464 return Ok(SchedulingAction::ExecuteDtors);
466 if self.threads[MAIN_THREAD].state == ThreadState::Terminated {
467 // The main thread terminated; stop the program.
468 if self.threads.iter().any(|thread| thread.state != ThreadState::Terminated) {
469 // FIXME: This check should be either configurable or just emit
470 // a warning. For example, it seems normal for a program to
471 // terminate without waiting for its detached threads to
472 // terminate. However, this case is not trivial to support
473 // because we also probably do not want to consider the memory
474 // owned by these threads as leaked.
475 throw_unsup_format!("the main thread terminated without waiting for other threads");
477 return Ok(SchedulingAction::Stop);
479 // At least for `pthread_cond_timedwait` we need to report timeout when
480 // the function is called already after the specified time even if a
481 // signal is received before the thread gets scheduled. Therefore, we
482 // need to schedule all timeout callbacks before we continue regular
486 // https://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_cond_timedwait.html#
487 let potential_sleep_time =
488 self.timeout_callbacks.values().map(|info| info.call_time.get_wait_time()).min();
489 if potential_sleep_time == Some(Duration::new(0, 0)) {
490 return Ok(SchedulingAction::ExecuteTimeoutCallback);
492 // No callbacks scheduled, pick a regular thread to execute.
493 if self.threads[self.active_thread].state == ThreadState::Enabled
494 && !self.yield_active_thread
496 // The currently active thread is still enabled, just continue with it.
497 return Ok(SchedulingAction::ExecuteStep);
499 // We need to pick a new thread for execution.
500 for (id, thread) in self.threads.iter_enumerated() {
501 if thread.state == ThreadState::Enabled {
502 if !self.yield_active_thread || id != self.active_thread {
503 self.active_thread = id;
508 self.yield_active_thread = false;
509 if self.threads[self.active_thread].state == ThreadState::Enabled {
510 return Ok(SchedulingAction::ExecuteStep);
512 // We have not found a thread to execute.
513 if self.threads.iter().all(|thread| thread.state == ThreadState::Terminated) {
514 unreachable!("all threads terminated without the main thread terminating?!");
515 } else if let Some(sleep_time) = potential_sleep_time {
516 // All threads are currently blocked, but we have unexecuted
517 // timeout_callbacks, which may unblock some of the threads. Hence,
518 // sleep until the first callback.
519 std::thread::sleep(sleep_time);
520 Ok(SchedulingAction::ExecuteTimeoutCallback)
522 throw_machine_stop!(TerminationInfo::Deadlock);
527 // Public interface to thread management.
528 impl<'mir, 'tcx: 'mir> EvalContextExt<'mir, 'tcx> for crate::MiriEvalContext<'mir, 'tcx> {}
529 pub trait EvalContextExt<'mir, 'tcx: 'mir>: crate::MiriEvalContextExt<'mir, 'tcx> {
530 /// Get a thread-specific allocation id for the given thread-local static.
531 /// If needed, allocate a new one.
532 fn get_or_create_thread_local_alloc_id(&mut self, def_id: DefId) -> InterpResult<'tcx, AllocId> {
533 let this = self.eval_context_mut();
535 if let Some(new_alloc_id) = this.machine.threads.get_thread_local_alloc_id(def_id) {
536 // We already have a thread-specific allocation id for this
537 // thread-local static.
540 // We need to allocate a thread-specific allocation id for this
541 // thread-local static.
542 // First, we compute the initial value for this static.
543 if tcx.is_foreign_item(def_id) {
544 throw_unsup_format!("foreign thread-local statics are not supported");
546 let allocation = tcx.eval_static_initializer(def_id)?;
547 // Create a fresh allocation with this content.
548 let new_alloc_id = this.memory.allocate_with(allocation.clone(), MiriMemoryKind::Tls.into()).alloc_id;
549 this.machine.threads.set_thread_local_alloc_id(def_id, new_alloc_id);
555 fn create_thread(&mut self) -> ThreadId {
556 let this = self.eval_context_mut();
557 this.machine.threads.create_thread()
561 fn detach_thread(&mut self, thread_id: ThreadId) -> InterpResult<'tcx> {
562 let this = self.eval_context_mut();
563 this.machine.threads.detach_thread(thread_id)
567 fn join_thread(&mut self, joined_thread_id: ThreadId) -> InterpResult<'tcx> {
568 let this = self.eval_context_mut();
569 this.machine.threads.join_thread(joined_thread_id)
573 fn set_active_thread(&mut self, thread_id: ThreadId) -> ThreadId {
574 let this = self.eval_context_mut();
575 this.machine.threads.set_active_thread_id(thread_id)
579 fn get_active_thread(&self) -> ThreadId {
580 let this = self.eval_context_ref();
581 this.machine.threads.get_active_thread_id()
585 fn active_thread_mut(&mut self) -> &mut Thread<'mir, 'tcx> {
586 let this = self.eval_context_mut();
587 this.machine.threads.active_thread_mut()
591 fn active_thread_ref(&self) -> &Thread<'mir, 'tcx> {
592 let this = self.eval_context_ref();
593 this.machine.threads.active_thread_ref()
597 fn get_total_thread_count(&self) -> usize {
598 let this = self.eval_context_ref();
599 this.machine.threads.get_total_thread_count()
603 fn has_terminated(&self, thread_id: ThreadId) -> bool {
604 let this = self.eval_context_ref();
605 this.machine.threads.has_terminated(thread_id)
609 fn enable_thread(&mut self, thread_id: ThreadId) {
610 let this = self.eval_context_mut();
611 this.machine.threads.enable_thread(thread_id);
615 fn active_thread_stack(&self) -> &[Frame<'mir, 'tcx, Tag, FrameData<'tcx>>] {
616 let this = self.eval_context_ref();
617 this.machine.threads.active_thread_stack()
621 fn active_thread_stack_mut(&mut self) -> &mut Vec<Frame<'mir, 'tcx, Tag, FrameData<'tcx>>> {
622 let this = self.eval_context_mut();
623 this.machine.threads.active_thread_stack_mut()
627 fn set_active_thread_name(&mut self, new_thread_name: Vec<u8>) {
628 let this = self.eval_context_mut();
629 this.machine.threads.set_thread_name(new_thread_name);
633 fn get_active_thread_name<'c>(&'c self) -> &'c [u8]
637 let this = self.eval_context_ref();
638 this.machine.threads.get_thread_name()
642 fn block_thread(&mut self, thread: ThreadId) {
643 let this = self.eval_context_mut();
644 this.machine.threads.block_thread(thread);
648 fn unblock_thread(&mut self, thread: ThreadId) {
649 let this = self.eval_context_mut();
650 this.machine.threads.unblock_thread(thread);
654 fn yield_active_thread(&mut self) {
655 let this = self.eval_context_mut();
656 this.machine.threads.yield_active_thread();
660 fn register_timeout_callback(
664 callback: TimeoutCallback<'mir, 'tcx>,
666 let this = self.eval_context_mut();
667 this.machine.threads.register_timeout_callback(thread, call_time, callback);
671 fn unregister_timeout_callback_if_exists(&mut self, thread: ThreadId) {
672 let this = self.eval_context_mut();
673 this.machine.threads.unregister_timeout_callback_if_exists(thread);
676 /// Execute a timeout callback on the callback's thread.
678 fn run_timeout_callback(&mut self) -> InterpResult<'tcx> {
679 let this = self.eval_context_mut();
680 let (thread, callback) =
681 this.machine.threads.get_ready_callback().expect("no callback found");
682 // This back-and-forth with `set_active_thread` is here because of two
684 // 1. Make the caller and not the callback responsible for changing
686 // 2. Make the scheduler the only place that can change the active
688 let old_thread = this.set_active_thread(thread);
690 this.set_active_thread(old_thread);
694 /// Decide which action to take next and on which thread.
696 fn schedule(&mut self) -> InterpResult<'tcx, SchedulingAction> {
697 let this = self.eval_context_mut();
698 this.machine.threads.schedule()
701 /// Handles thread termination of the active thread: wakes up threads joining on this one,
702 /// and deallocated thread-local statics.
704 /// This is called from `tls.rs` after handling the TLS dtors.
706 fn thread_terminated(&mut self) -> InterpResult<'tcx> {
707 let this = self.eval_context_mut();
708 for alloc_id in this.machine.threads.thread_terminated() {
709 let ptr = this.memory.global_base_pointer(alloc_id.into())?;
710 this.memory.deallocate(ptr, None, MiriMemoryKind::Tls.into())?;