Struct ThreadExceptionState 

pub struct ThreadExceptionState { /* private fields */ }

Per-thread exception handling state.

This structure tracks the complete exception handling state for a single emulated thread. It manages the current exception, pending cleanup handlers, filter evaluation, and control flow during exception processing.

Responsibilities

• Tracking the active exception and its information
• Managing the queue of pending finally blocks
• Handling filter clause evaluation state
• Processing rethrow requests from catch handlers
• Tracking leave instruction targets through finally blocks

Lifecycle

1. Create with new() (or Default::default())
2. Set exception with set_exception() when thrown
3. Push finally blocks with push_finally()
4. Pop and execute finally blocks with pop_finally()
5. Enter catch with enter_catch() to handle exception
6. Clear with clear() when exception is fully handled

Example

let mut state = ThreadExceptionState::new();

// Exception thrown
state.set_exception(exception_info);

// Queue finally blocks found during search
state.push_finally(method, offset, Some(leave_target));

// Execute finally blocks
while let Some(finally) = state.pop_finally() {
    // Execute finally handler...
}

// Enter catch handler
state.enter_catch();

Implementations

impl ThreadExceptionState

pub fn new() -> Self

Creates a new exception state with no active exception.

Returns

A new ThreadExceptionState in the initial (no exception) state.

pub fn has_exception(&self) -> bool

Checks if there is an active exception.

Returns

true if an exception is currently active.

pub fn exception(&self) -> Option<&ExceptionInfo>

Gets a reference to the current exception information.

Returns

A reference to the ExceptionInfo if an exception is active, or None.

pub fn get_exception_value(&self) -> Option<EmValue>

Gets the current exception as an EmValue.

Returns

Some(EmValue::ObjectRef(...)) if an exception is active, None otherwise.

pub fn set_exception(&mut self, exception: ExceptionInfo)

Sets the current exception.

This should be called when an exception is thrown. It sets the exception info and enters exception handling mode.

Arguments

• exception - The exception information to set

pub fn take_exception(&mut self) -> Option<ExceptionInfo>

Takes (consumes) the current exception.

Removes the exception from this state and returns it. Also clears the handling flag.

Returns

The exception info if one was active, or None.

pub fn take_exception_as_value(&mut self) -> Option<EmValue>

Takes (consumes) the exception as an EmValue.

Removes the exception from this state and returns it as an EmValue. Also clears the handling flag.

Returns

Some(EmValue::ObjectRef(...)) if an exception was active, None otherwise.

pub fn clear(&mut self)

Clears all exception state.

Resets the exception state to its initial condition, clearing the exception, pending finally blocks, filter state, and all other fields. Call this when an exception has been fully handled or when resetting the thread state.

pub fn is_handling(&self) -> bool

Checks if exception handling is in progress.

Returns

true if currently handling an exception (from throw until catch or propagation).

pub fn push_finally( &mut self, method: Token, handler_offset: u32, leave_target: Option<u32>, )

Pushes a pending finally block onto the execution queue.

Finally blocks are executed in LIFO order (last pushed = first executed).

Arguments

• method - The method containing the finally block
• handler_offset - The IL offset of the finally handler
• leave_target - Optional target offset for leave instructions

pub fn pop_finally(&mut self) -> Option<PendingFinally>

Pops and returns the next pending finally block.

Returns the most recently pushed finally block (LIFO order).

Returns

The next finally block to execute, or None if no blocks are pending.

pub fn has_pending_finally(&self) -> bool

Checks if there are pending finally blocks.

Returns

true if there are finally blocks waiting to be executed.

pub fn pending_finally_count(&self) -> usize

Gets the number of pending finally blocks.

Returns

The count of finally blocks in the queue.

pub fn request_rethrow(&mut self)

Requests a rethrow of the current exception.

Called when a rethrow instruction is executed inside a catch handler. The exception will be propagated again after executing any pending finally blocks.

pub fn take_rethrow_request(&mut self) -> bool

Takes and clears the rethrow request.

This method checks if a rethrow was requested and clears the flag. It should be called after exiting a catch handler to determine if the exception should be propagated.

Returns

true if a rethrow was requested since the last check.

pub fn enter_catch(&mut self)

Enters a catch handler, clearing the exception state.

Called when execution transfers to a catch handler. The exception is considered handled and the state is cleared.

Note: Use enter_catch_handler if you need to support rethrow from within the catch block.

pub fn enter_finally(&mut self)

Enters a finally handler.

Called when execution transfers to a finally handler. Exception state is preserved during finally execution.

pub fn exit_finally(&mut self, exception_to_restore: Option<ExceptionInfo>)

Exits a finally handler.

Called when a finally handler completes (via endfinally). If a rethrow was requested, restores the exception for continued propagation.

Arguments

• exception_to_restore - The exception to restore if rethrow was requested

pub fn leave_target(&self) -> Option<u32>

Gets the leave target offset.

Returns

The target IL offset for a pending leave instruction, or None.

pub fn set_leave_target(&mut self, target: Option<u32>)

Sets the leave target offset.

Called when a leave instruction is encountered and finally blocks must execute before reaching the target.

Arguments

• target - The target offset, or None to clear

pub fn take_leave_target(&mut self) -> Option<u32>

Takes the leave target (returns and clears it).

Returns

The leave target offset if one was set, or None.

pub fn in_filter(&self) -> bool

Checks if currently in filter evaluation.

Returns

true if currently evaluating a filter clause.

pub fn enter_filter(&mut self, handler_offset: u32)

Enters filter evaluation mode with the given handler offset.

Call this when starting to evaluate a filter clause. The handler_offset is stored so that if the filter accepts, execution can transfer to it.

Arguments

• handler_offset - The IL offset of the handler to enter if filter accepts

pub fn set_in_filter(&mut self, in_filter: bool)

Sets the filter evaluation state.

Arguments

• in_filter - true when entering filter evaluation, false when exiting

Note

Prefer using enter_filter when entering a filter, as it also stores the handler offset. Use set_in_filter(false) to exit.

pub fn filter_handler_offset(&self) -> Option<u32>

Gets the handler offset for the current filter.

If currently evaluating a filter and the filter accepts, execution should transfer to this offset.

Returns

The handler offset if in a filter, or None.

pub fn filter_result(&self) -> Option<bool>

Gets the filter evaluation result.

Returns

• Some(true) - Filter accepted, enter the handler
• Some(false) - Filter rejected, continue searching
• None - Filter not yet evaluated

pub fn set_filter_result(&mut self, result: Option<bool>)

Sets the filter evaluation result.

Called after evaluating the filter code to record whether the handler should be entered.

Arguments

• result - The filter result (Some(true) to accept, Some(false) to reject)

pub fn exception_origin_offset(&self) -> Option<u32>

Gets the exception origin offset.

This is the IL offset where the exception was originally thrown, used for handler search during rethrow.

Returns

The origin offset if set, or None.

pub fn current_handler_offset(&self) -> Option<u32>

Gets the current handler offset.

This is the IL offset of the handler currently executing, used to skip it during rethrow handler search.

Returns

The handler offset if set, or None.

pub fn current_handler_method(&self) -> Option<Token>

Returns the method that owns the current catch handler.

pub fn enter_catch_handler( &mut self, method: Token, origin_offset: u32, handler_offset: u32, )

Enters a catch handler with tracking for rethrow support.

Unlike enter_catch, this preserves the exception value to support the rethrow instruction within the catch block.

Arguments

• method - The method token that owns this catch handler
• origin_offset - The IL offset where the exception was thrown
• handler_offset - The IL offset of this catch handler

pub fn leave_catch_handler(&mut self)

Leaves a catch handler normally via leave instruction.

Called when exiting a catch handler through normal control flow (not via rethrow). Clears exception-related state.

pub fn in_unwind_finally(&self) -> bool

Returns whether we are currently in a finally block entered during exception unwinding.

pub fn set_in_unwind_finally(&mut self, in_unwind: bool)

Sets the unwind-finally state.

Set to true when entering a finally block during exception unwinding. Set to false when the finally completes normally via endfinally.

pub fn exception_mut(&mut self) -> Option<&mut ExceptionInfo>

Gets a mutable reference to the current exception info.

Used to build stack traces during unwinding without consuming the exception.

pub fn replace_exception_in_unwind_finally( &mut self, new_exception: ExceptionInfo, )

Handles a new exception thrown during an unwind-finally.

Per ECMA-335 §II.12.4.2.5: the old exception is abandoned and the new exception replaces it. The pending finally queue is cleared since the old unwind chain is no longer relevant.

pub fn clear_exception(&mut self)

Clears exception-related state when fully handled.

Clears the filter result and handler tracking but does not affect other state like pending finally blocks.

Trait Implementations

impl Clone for ThreadExceptionState

fn clone(&self) -> ThreadExceptionState

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ThreadExceptionState

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

Formats the value using the given formatter.

impl Default for ThreadExceptionState

fn default() -> ThreadExceptionState

Returns the “default value” for a type.