Struct ThreadState 

pub struct ThreadState<T> {

    pub dettid: DetTid,
    pub detpid: Option<DetTid>,
    pub physical_tid: Option<i32>,
    pub mm_id: MmId,
    pub pedigree: Pedigree,
    pub stats: ThreadStats,
    pub preemption_points: Option<ThreadHistoryIterator>,
    pub interrupt_at: BTreeSet<u64>,
    pub clone_flags: Option<CloneFlags>,
    pub pending_vfork: Option<PendingVfork>,
    pub file_metadata: Arc<Mutex<FileMetadata>>,
    pub prng: Pcg64Mcg,
    pub chaos_prng: Pcg64Mcg,
    pub thread_logical_time: DetTime,
    pub committed_clock_value: u64,
    pub record_or_replay: T,
    pub end_of_timeslice: Option<LogicalTime>,
    pub replay_rcb_end: Option<u64>,
    pub last_replay_change_point: Option<LogicalTime>,
    pub chaos_epoch: u64,
    pub chaos_slowdown_factor: RcbTimeMultiplier,
    pub chaos_slowdown_active: bool,
    pub pending_chaos_epochs: Vec<ChaosEpochTransition>,
    pub max_timeslice_end: Option<LogicalTime>,
    pub last_grant_deadline: Option<Duration>,
    pub last_rcb_timer: Option<u64>,
    pub last_rcb_timer_is_max: bool,
    pub lone_grant: bool,
    pub lone_slice_end: Option<u64>,
    pub replaying_lone_slice_end: Option<u64>,
    pub lone_replay_unsound: bool,
    /* private fields */
}

The Detcore per-thread state.

Fields

dettid: DetTid

The deterministic thread ID of the this thread.

detpid: Option<DetTid>

The deterministic process ID of the this thread.

physical_tid: Option<i32>

Host thread ID supplied by a backend whose scheduler identity is virtual. None keeps the existing direct-ID behavior for other backends.

mm_id: MmId

Linux memory address space shared by tasks created with CLONE_VM.

pedigree: Pedigree

This threads path within the thread/process ancestry tree. (The terminology comes from Cilk.)

stats: ThreadStats

Counting various events.

preemption_points: Option<ThreadHistoryIterator>

In chaos mode with –replay-preemptions-from, we hold a list of our future preemption points.

interrupt_at: BTreeSet<u64>

User defined interruption points

clone_flags: Option<CloneFlags>

clone flags when SYS_clone is called.

This is just a place to stash the value temporarily, where it can be read out by the child thread upon init_thread_state. After that point, it is consumed by the child and becomes None again.

Stated differently, this is just for message-passing communication.

pending_vfork: Option<PendingVfork>

Registration metadata for a child whose parent cannot resume until the backend finishes the child. The child consumes this in handle_thread_start; the parent clears its copy when injection returns.

file_metadata: Arc<Mutex<FileMetadata>>

Shared file metadata among all threads in the same process. Initialized for new threads (shared or fresh), and then overwritten again on execve.

prng: Pcg64Mcg

pseudo random number state

chaos_prng: Pcg64Mcg

RNG to drive chaos scheduling decisions, separate from other (guest) RNG.

thread_logical_time: DetTime

logical time, measuring progress of this thread and only this thread.

committed_clock_value: u64

the last RCB clock value committed to thread_logical_time

record_or_replay: T

Thread state associated with record/replay.

end_of_timeslice: Option<LogicalTime>

How much longer does this thread get to run before it must check-in with the scheduler? Note that this notion of time slice can extend across a region of time that includes syscalls (and thus handlers).

If set to None, the thread can run indefinitely without preemption.

This is in units of virtual Nanoseconds. And it is an exact time in the future, not a relative duration.

replay_rcb_end: Option<u64>

Exact per-thread PMU RCB target for the active preemption-replay slice. None selects the legacy logical-time deadline path.

last_replay_change_point: Option<LogicalTime>

In a preemption replay, the logical time of the last priority change point this thread filed (ThreadState::file_replay_change_point).

chaos_epoch: u64

Deterministic chaos epoch this thread was in at its last next_timeslice. Used only to detect epoch transitions for CHAOSEPOCH logging; the epoch itself is recomputed each slice from thread_logical_time. Sentinel u64::MAX guarantees the first slice always logs its initial epoch.

chaos_slowdown_factor: RcbTimeMultiplier

Exact multiplier currently used to convert this thread’s RCBs to virtual time.

chaos_slowdown_active: bool

True when live chaos configuration or a replay artifact supplies the factor.

pending_chaos_epochs: Vec<ChaosEpochTransition>

Transitions waiting to be committed into the preemption artifact.

max_timeslice_end: Option<LogicalTime>

Absolute deadline enforced by the PMU-backed --max-timeslice timer. This is separate from end_of_timeslice so syscall-heavy workloads can use a shorter, cheap target deadline.

last_grant_deadline: Option<Duration>

The deadline hint carried by the last scheduler reply this thread received (ThreadState::cap_timeslice_at_deadline). Applied when the reply arrives, and again by the two paths that then install a fresh slice end: thread start and the exec continuation.

last_rcb_timer: Option<u64>

Track what our last timer was set for, just to double check that RCB timers are behaving as expected and see if we went over. (For exmaple, this behaves badly if threads are not pinned and our we migrate between cores.)

last_rcb_timer_is_max: bool

Whether last_rcb_timer represents the maximum deadline rather than a manual interrupt.

lone_grant: bool

Whether the scheduler’s last reply to this thread was a grant that found it the only thread able to run before it next enters Detcore (GlobalResponse::WithLoneGrant). Every reply without that mark clears it.

lone_slice_end: Option<u64>

While the thread runs alone (Config::replays_lone_preemptions): the branch count, in committed_clock_value units, at which its current timeslice ends. No timer stops the guest there; the thread’s next entry into Detcore processes every such end at or before the count it reached, in order (Detcore::catch_up_lone_slice_ends).

replaying_lone_slice_end: Option<u64>

While such an end is processed: its branch count, which the clock update reads in place of the hardware counter.

lone_replay_unsound: bool

Set when a grant while such an end was processed did not find the thread alone, which the scheduler’s predicate rules out; taken by Detcore::catch_up_lone_slice_ends, which reports it.

Implementations

impl<T> ThreadState<T>

pub fn reseed_child_rngs(&mut self, parent: &Self, entropy: u128)

Replaces the host-TID-derived child streams with a backend-provided, deterministic identity before the thread enters its start hook.

pub fn new(pid: DetPid, cfg: &Config, record_or_replay: T) -> Self

Create a fresh new thread state from nothing. In practice this is only used for the thread state of the root thread of the container.

pub fn apply_initial_random_state( &mut self, bytes: &[u8], config: &Config, image: InitialImage, ) -> Result<(), Errno>

Apply a required, authenticated initial-image random handoff to the normal root. Errors are tool initialization failures, never guest errno.

pub fn mk_request(&self, rid: ResourceID, perm: Permission) -> Resources

Build a singleton resource request from the current thread.

pub fn chaos_prng_next_u64(&mut self, msg: &str) -> u64

Generate the next random number using the thread-local chaos_seed.

pub fn add_fd( &self, fd: RawFd, flags: OFlag, ty: FdType, stat: Option<DetStat>, ) -> Result<(), Errno>

Add a new fd, with optional stat data, have side effects on other threads.

If stat data is not available, then perform an extra stat ourselves to populate it.

Arguments

• fd - file descriptor to add

• flags - flags when creating fd

• ty - fd type (regular file, socket, pipe, etc..)

• stat - stat returned from fstat

pub fn set_open_file_creator(&mut self, creator: DetTid)

Overrides the task identity embedded in subsequently allocated open-file descriptions.

pub fn with_detfd<F, U>(&self, fd: RawFd, f: F) -> Result<U, Errno>

where F: FnMut(&mut DetFd) -> U,

Get a mutable reference of DetFd from a raw file descriptor, and run mutable function f on it (&mut DetFd).

pub fn exec_blocking_overrides(&self) -> BTreeSet<RawFd>

Preserve logical blocking for scheduler-managed descriptors when exec replaces an in-process tool and its descriptor metadata.

pub fn promote_shared_open_files(&self) -> Result<(), SharedOpenFileError>

Promote the OFDs whose model must stay one copy – random devices (their cursor) and timerfds (their virtual-time expirations, crate::fd::VirtualTimerfd) – before a backend physically copies or replaces its in-process Tool. The shared model owns their full state; this does not promote sockets or other OFDs. The record sequences of per-process files move to Detcore’s global state on their own (share_procfs_sequences, first). Call only while this task owns its serial grant, before the native lifecycle operation can expose a child/new image. Ptrace’s host-side Arc needs no promotion. See https://github.com/rrnewton/hermit/issues/4381.

pub fn share_procfs_sequences(&self)

Before a backend whose tool runs in each guest process physically copies this process (a fork) or replaces its image: every description of a per-process file that follows its record’s sequence keeps that sequence in Detcore’s global state from then on, so the copies a fork makes share it as Linux’s processes share the one struct file and seq_file (ProcfsFile::share_sequence, Detcore::take_procfs_sequence). Local and RPC-free: the first operation after the fork, in either process, finds no sequence there yet and keeps its copy, which is the one the fork made. Runs in the caller’s turn, before the copy exists (promote_shared_open_files, and Detcore::handle_clone_family for SaBRe, whose runtime promotes nothing).

pub fn reset_copied_open_file_locks(&self)

Rebuild only process-local locks after a physical process copy. This is RPC-free and precedes the child’s first scheduler admission. Ordinary same-process table clones retain their original shared locks.

pub fn has_unsafe_vfork_flock_state(&self) -> bool

Whether some open file description holds a flock mode Detcore knows, or was invalidated by a process copy after a flock was granted through it (FileMetadata::has_unsafe_vfork_flock_state).

pub fn has_unsafe_vfork_ofd_state(&self) -> bool

Whether a description in this table may hold an OFD lock. A copied vfork child (DBT) runs its lock calls natively, so the procfs::locks::LockLedger entry of such a description could go stale and admit a host’s identical /proc/locks row.

pub fn forget_flock_modes(&self)

A new process can change every inherited open file description through a separately hosted tool state, so neither side may keep treating its cached flock mode as authoritative after fork.

pub fn remove_fd(&self, fd: RawFd) -> Option<OpenFileId>

remove a rawfd

pub fn dup_fd( &mut self, oldfd: RawFd, newfd: RawFd, flags: OFlag, ) -> Result<Option<OpenFileId>, Errno>

dup raw fds.

pub fn thread_prng(&mut self) -> &mut Pcg64Mcg

get thread prng, note this rng is deterministic and should not be used for crypto.

pub fn next_timeslice(&mut self, cfg: &Config) -> Option<Priority>

Choose the logical target and PMU maximum deadlines for the next timeslice.

Effects:

• Sets end_of_timeslice for the new timeslice.
• Sets max_timeslice_end when PMU-backed preemption is enabled.
• Resets the statistics for the timeslice.

Returns: an optional new priority.

pub fn reset_timeslice_for_explicit_yield(&mut self)

Close the current logical-timeslice statistics without selecting a new preemption point. Used when preemption replay reaches a deterministic guest sched_yield boundary.

pub fn guest_past_first_execve(&self) -> bool

Are we within the execution of the (first) guest binary or any child processes called by it? Returns false if we are in the very beginning of execution, when the hermit container has forked our process, but we have not yet executed the guest binary. There are few guarantees during this early initialization period, and Detcore should make no assumptions, nor guarantee determinism!

Trait Implementations

impl<T> AsMut<T> for ThreadState<T>

fn as_mut(&mut self) -> &mut T

Converts this type into a mutable reference of the (usually inferred) input type.

impl<T> AsRef<T> for ThreadState<T>

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: Clone> Clone for ThreadState<T>

fn clone(&self) -> ThreadState<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for ThreadState<T>

We cannot assume that the record_or_replay “subtool” is Debug, so it is handy to be able to print the Detcore threadstate alone.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Default for ThreadState<T>

fn default() -> Self

Returns the “default value” for a type.

impl<'de, T> Deserialize<'de> for ThreadState<T>

where T: Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T> Serialize for ThreadState<T>

where T: Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.