pub struct SequenceContext { /* private fields */ }Expand description
A point in a running sequence, and everything reachable from it
(SequenceContext).
This is what an expression calls ThisContext, obtained from
Thread::get_sequence_context. It is
the door to the variable scopes, Locals, Parameters, FileGlobals,
StationGlobals, and to RunState.
§Lifetimes: what may outlive the run, and what may not
A host holding the wrong reference after an execution ends keeps a COM object alive on a finished run. The documentation draws the line explicitly: these exist before, and persist after, the execution, ///
station_globals, shared by the whole session, and modifications from one execution are seen by all of themsequence_file
, while everything else belongs to the run, file_globals
most notably: it is the execution’s own copy, and writing to it does not
touch the file’s stored defaults.
So the safe pattern for a host is to read what it needs from a context while
the run is alive and keep the data, not the reference. Values that must
outlive the run come from the engine or the file instead:
Engine::globals for station globals with no
execution at all, and
SequenceFile::file_globals_default_values
for the file’s edit-time defaults.
Implementations§
Source§impl SequenceContext
impl SequenceContext
Sourcepub fn as_property_object(&self) -> Result<PropertyObject, Error>
pub fn as_property_object(&self) -> Result<PropertyObject, Error>
Sourcepub fn locals(&self) -> Result<PropertyObject, Error>
pub fn locals(&self) -> Result<PropertyObject, Error>
Sourcepub fn parameters(&self) -> Result<PropertyObject, Error>
pub fn parameters(&self) -> Result<PropertyObject, Error>
Sourcepub fn file_globals(&self) -> Result<PropertyObject, Error>
pub fn file_globals(&self) -> Result<PropertyObject, Error>
The executing file’s globals (SequenceContext.FileGlobals).
Belongs to the run. This is the execution’s own copy: changes here
do not affect the defaults stored in the sequence file, and the object
is meaningless once the run is over. Read what is needed now, or use
SequenceFile::file_globals_default_values
for the values that live in the file.
§Errors
Error if the COM call fails or returns an unexpected type.
Sourcepub fn station_globals(&self) -> Result<PropertyObject, Error>
pub fn station_globals(&self) -> Result<PropertyObject, Error>
The station’s global variables (SequenceContext.StationGlobals).
Outlives the run, and is shared: a change made here is seen by every
execution in the session, and persists on disk. Reachable without any
execution through Engine::globals, which is
the better route when no run is involved.
§Errors
Error if the COM call fails or returns an unexpected type.
Sourcepub fn sequence_file(&self) -> Result<SequenceFile, Error>
pub fn sequence_file(&self) -> Result<SequenceFile, Error>
Sourcepub fn call_stack_depth(&self) -> Result<i32, Error>
pub fn call_stack_depth(&self) -> Result<i32, Error>
Sourcepub fn step_index(&self) -> Result<i32, Error>
pub fn step_index(&self) -> Result<i32, Error>
Sourcepub fn num_steps_executed(&self) -> Result<i32, Error>
pub fn num_steps_executed(&self) -> Result<i32, Error>
Sourcepub fn sequence_failed(&self) -> Result<bool, Error>
pub fn sequence_failed(&self) -> Result<bool, Error>
Sourcepub fn error_reported(&self) -> Result<bool, Error>
pub fn error_reported(&self) -> Result<bool, Error>
Sourcepub fn run_time_error_message(&self) -> Result<String, Error>
pub fn run_time_error_message(&self) -> Result<String, Error>
Sourcepub fn step(&self) -> Result<Step, Error>
pub fn step(&self) -> Result<Step, Error>
The step being run right now (SequenceContext.Step).
Fallible by nature. The engine documents this property as existing only while a step executes, between steps, and at a breakpoint, there is no current step. An error here is a legitimate state, not a defect, which is why it is not reported as an empty value.
§Errors
Error if no step is executing, or the COM call fails.