Struct Thread

Source

pub struct Thread { /* private fields */ }

Expand description

A thread within an Execution.

Every execution has at least one. A sequence that starts a parallel or asynchronous step gains more, which is why a front end tracks progress per thread rather than per execution.

Implementations§

Source §

impl Thread

Source

pub fn as_property_object(&self) -> Result<PropertyObject, Error>

The thread as a property tree (Thread.AsPropertyObject).

§Errors

Error if the COM call fails or returns an unexpected type.

Source

pub fn id(&self) -> Result<i32, Error>

The thread’s identifier within its execution (Thread.Id).

§Errors

Error if the COM call fails or returns an unexpected type.

Source

pub fn unique_thread_id(&self) -> Result<String, Error>

An identifier unique across the whole session (Thread.UniqueThreadId).

id only distinguishes threads within one execution, so a host serving several executions keys on this instead.

§Errors

Error if the COM call fails or returns an unexpected type.

Source

pub fn display_name(&self) -> Result<String, Error>

The name a front end shows for this thread (Thread.DisplayName).

§Errors

Error if the COM call fails or returns an unexpected type.

Source

pub fn call_stack_size(&self) -> Result<i32, Error>

How deep the call stack currently is (Thread.CallStackSize).

Index 0 is the innermost frame, which is what get_sequence_context usually wants.

§Errors

Error if the COM call fails or returns an unexpected type.

Source

pub fn externally_suspended(&self) -> Result<bool, Error>

Whether a requested suspend has actually taken effect (Thread.ExternallySuspended).

Execution::suspend only asks. This is how a caller learns the engine has acted, and the reason a suspend followed immediately by a resume is a race: the resume can arrive before the suspend takes hold, leaving the run stopped for good.

§Errors

Error if the COM call fails or returns an unexpected type.

Source

pub fn execution(&self) -> Result<Execution, Error>

The execution this thread belongs to (Thread.Execution).

§Errors

Error if the COM call fails or returns an unexpected type.

Source

pub fn get_sequence_context( &self, call_stack_index: i32, ) -> Result<SequenceContext, Error>

The sequence context at a call-stack frame (Thread.GetSequenceContext).

Index 0 is the innermost frame, the sequence running right now.

This is the route to RunState, Locals, FileGlobals and StationGlobals for a live run. Mind what may outlive the run: NI documents StationGlobals, RunState.InitialSelection, RunState.SequenceFile and RunState.ProcessModelClient as existing before and persisting after the execution, and everything else in the context as belonging to it. FileGlobals in particular is the run’s own copy, so keeping one past the execution holds a reference to a finished run, read what is needed while it is alive, or take the edit-time defaults from SequenceFile::file_globals_default_values instead.

The engine declares two parameters: the call stack index, and an [out] frame id (VT_BYREF | VT_I4). Both must be present in the call even though only the first carries information, supplying one gives DISP_E_BADPARAMCOUNT. The second is passed empty, which the engine accepts as “no output wanted”; reading the frame id back would need byref support this crate does not have yet.

§Errors

Error if the index is out of range or the COM call fails.

Source

pub fn set_step_over(&self) -> Result<(), Error>

Asks this thread to stop again once the next step finishes (Thread.SetStepOver).

Arms a one-shot stop; it does not start the thread moving. Pair it with resume to actually step.

The engine also has Execution.StepOver, which arms and resumes in one call but always acts on the foreground thread. This crate does not wrap it yet. Going through the thread is the only way to say which thread to step, which is what a host serving a panel with several threads needs.

§Errors

Error if the COM call fails.

Source

pub fn set_step_into(&self) -> Result<(), Error>

Arms a stop at the first step inside whatever the next step calls (Thread.SetStepInto).

Does not resume the thread. See set_step_over.

§Errors

Error if the COM call fails.

Source

pub fn set_step_out(&self) -> Result<(), Error>

Arms a stop once the current sequence returns to its caller (Thread.SetStepOut).

Does not resume the thread. See set_step_over.

§Errors

Error if the COM call fails.

Source

pub fn clear_temporary_breakpoint(&self) -> Result<(), Error>

Clears a stop armed by one of the set_step_* members (Thread.ClearTemporaryBreakpoint).

Only the temporary one. Breakpoints set on a step are untouched.

§Errors

Error if the COM call fails.

Source

pub fn clear_current_rte(&self) -> Result<(), Error>

Clears the run-time error sitting on the current step (Thread.ClearCurrentRTE).

Resets the step’s recorded error so the thread carries on as though it had not happened. This is how a host answers a run-time error by ignoring it, rather than letting the station’s configured response decide.

Only meaningful while a run-time error is actually outstanding. Called on a thread that has none, a live engine answers TS_Err_UnexpectedType rather than doing nothing, so a host should call this in response to a run-time error and not speculatively.

§Errors

Error if there is no run-time error to clear, or the COM call fails.

Source

pub fn flush_post_results(&self) -> Result<(), Error>

Hands whatever results have piled up to the post-results callbacks now (Thread.FlushPostResults).

Results are normally batched. A host that wants a client to see them sooner can force the handover; with nothing accumulated the call does nothing, so it is safe to make on a timer.

§Errors

Error if the COM call fails.

Source

pub fn will_step_into_module(&self) -> Result<bool, Error>

Whether the run is about to step into the current step’s code module (Thread.WillStepIntoModule).

Read this only from a pre-step substep. That is the one place it means anything: it reports true there when the run will suspend inside the module belonging to the step that owns the substep. Read from anywhere else, an expression or a step’s own code module, the engine answers false regardless of what the run is doing, so a false here is not evidence that stepping is off.

§Errors

Error if the COM call fails or returns an unexpected type.

Source

pub fn wait_for_end( &self, milliseconds: i32, process_windows_messages: bool, ) -> Result<bool, Error>

Waits for this thread to finish (Thread.WaitForEnd).

Returns true when the thread ended and false when the wait ran out first. Pass -1 for milliseconds to wait with no limit, which is worth avoiding in a host that has to stay answerable.

process_windows_messages decides whether the calling thread keeps pumping while it waits. A host on a COM apartment should pass true: stop pumping and the engine cannot deliver into this apartment, so a wait meant to end can sit until the timeout instead.

Waiting is not the only obligation. This pumps but does not drain the engine’s message queue, so a sequence posting a synchronous message stays blocked on a host that only waits here. Draining the queue is separate work.

The two optional arguments the engine accepts, a step to store results in and a calling sequence context, are not exposed. Both take an object this crate has no route to from outside a running sequence.

§Errors

Error if the COM call fails or returns an unexpected type.

Source

pub fn termination_option( &self, ) -> Result<Result<ThreadTerminationOption, i32>, Error>

How this thread answers a request to terminate its execution (Thread.TerminationOption).

The inner Result carries the raw number when the engine names an option this build does not, rather than mapping it onto a neighbour.

§Errors

Error if the COM call fails or returns an unexpected type.

Source

pub fn set_termination_option( &self, option: ThreadTerminationOption, ) -> Result<(), Error>

Chooses how this thread answers a terminate request (Thread.TerminationOption).

§Errors

Error if the COM call fails.

Source

pub fn resume(&self) -> Result<(), Error>

Starts this thread running (Thread.Resume).

Releases a thread created suspended, which is how a sequence call step can hand one back before it runs. It is also the second half of a step, once set_step_over, set_step_into or set_step_out has armed one.

This does not continue a run stopped at a breakpoint. Measured against a live engine: after a breakpoint stop, calling this leaves the run where it is and the execution never ends. Use Execution::resume for that, which continued the same run in about 200 ms.

§Errors

Error if the COM call fails.

Source

pub fn post_ui_message_ex( &self, event_code: i32, numeric_data: f64, string_data: &str, activex_data: Option<&PropertyObject>, synchronous: bool, ) -> Result<(), Error>

Sends a message to whatever is watching this execution (Thread.PostUIMessageEx).

The outbound half of a two-way bridge: the sequence reports, a host forwards.

Pass synchronous = true in the ordinary case. It blocks the posting thread until the host acknowledges, which is what applies backpressure: posting faster than the host drains grows the queue without bound and eventually makes the host unresponsive. The cost is that a host which never drains its queue stalls the sequence instead, so a host owes the engine an acknowledge for every message it takes.

activex_data is the structured payload. Pass a container and the host reads the whole tree back from UIMessage::activex_data, instead of the two of them agreeing on how to pack fields into string_data. Pass None to leave the slot empty, which is a null object reference rather than an absent argument.

A message a host defines for itself should use a code at or above UIMessageCode::USER_MESSAGE_BASE, which is the range the engine reserves for callers.