Pipeline Reference

Every method on the runtime types a module’s own code calls, with the file each lives in. The handful the generated shell and the macros use, such as Pipeline::new, are public for them and are not listed.

Pipeline<'ps> (crates/pwrs/src/pipeline.rs, worker.rs)

The pipeline-thread token, !Send and !Sync, created by the runtime for one phase and passed to begin, process and end as &Pipeline<'_>.

The four writers take a &str, so a caller that formats one pays the format and the allocation whether or not anything reads the result: the engine decides that on the managed side, after the crossing. The verbose!, debug!, warning! and information! macros wrap the _if methods around a format, which is the short way to write it:

pwrs::verbose!(ps, "greeting {}", self.name)?;

A record counts as kept where the engine keeps one written by its own Write-* cmdlets, measured in pwsh 7.6.6 and Windows PowerShell 5.1.26100.9444. A verbose or debug record is kept only where it is shown. A warning is also kept under SilentlyContinue, in -WarningVariable, and an information record under SilentlyContinue, the default, reaches -InformationVariable and a 6> redirection. Under Ignore a warning or information record is written only when its -WarningVariable or -InformationVariable is bound: pwsh 7.6.6 fills the variable and Windows PowerShell 5.1 does not.

Order is AsReady or Input. A worker panic in any of the parallel helpers becomes a terminating PwrsWorkerPanic error, and no item starts after it. The pool is std threads; the parallel feature swaps in Flynnel for all of them, which changes nothing about these signatures or the module’s PowerShell surface.

Every method that reaches a stream or session state returns an error when the engine refuses (status 3 off-thread, status 5 when the pipeline stopped, status 1 for a managed exception); the error’s message is the exception’s Type: Message.

Progress (progress.rs)

Progress { activity_id: i32, parent_activity_id: i32, activity: String, status: String, current_operation: String, percent_complete: i32, seconds_remaining: i32, completed: bool }, a record for Pipeline::write_progress and Worker::write_progress with every field a ProgressRecord has; Clone, Debug, PartialEq, Eq.

The engine refuses a record whose activity or status is empty, whose activity id is negative, or whose parent activity id is its own activity id, and the write returns its error.

Worker<T> (worker.rs)

A worker thread’s way to the pipeline that started it: Clone, Send and Sync. T defaults to Infallible, a worker with no output, which is what par_map_with and par_for_each_with hand out; stream_from_worker hands out a Worker<T> whose output is T. Each record goes to the pipeline thread, which writes it on its stream in the order sent; of the progress records for one activity waiting together, only the last is written. Every method that sends answers whether the pipeline took the record, false once stopping() is true.

StopSignal (worker.rs) is Clone and Send: is_set(&self) -> bool.

StopWaker (stop.rs)

From Pipeline::on_stop: a guard over the waker the phase registered, with no methods. Dropping it unregisters the waker and frees it if it has not run. The waker and the guard share one slot on the cmdlet’s instance; whichever of the stop and the guard empties the slot first owns the waker, so it runs at most once and is never freed while it runs. A waker that panics is caught on the stopping thread and reported on standard error, since nothing may unwind across the native export the stop arrives through.

Workers (worker.rs)

From Pipeline::workers(count): count(&self) -> usize, and par_map, par_map_with, par_for_each and par_for_each_with with the Pipeline signatures, running at most count items at once. The default pool starts that many threads for the call, or one per item when there are fewer items; under the parallel feature they are tasks on Flynnel’s pool, which also runs no more at once than it has workers.

PsObject (object.rs, dynamic.rs, pinned.rs)

An owned GCHandle; Send, Sync, Clone (a second handle to the same object), Default ($null).

Free functions in pwrs::object: new_psobject(type_name: &str) -> PsObject, add_note(obj: &PsObject, name: &str, value: PsObject) -> PsResult<()>, and property(obj: &PsObject, name: &str) -> PsResult<PsObject>, which reads one back by name, note properties included, and fails for a name the object does not carry rather than reading as $null. PsObject::get goes to the underlying .NET object instead, so it does not see a note.

Pinned<'a, T>, PsMemory<T>, PsMemoryView<T> and PsRevocation (pinned.rs)

Pinned<'a, T> derefs to [T] and [T] mutably; releases the pin on drop. Must not outlive the phase.

PsMemory<T: Primitive>: zeroed(len: usize) -> PsResult<PsMemory<T>>, from_slice(&[T]) -> PsResult<PsMemory<T>>, TryFrom<Vec<T>>, len(), is_empty(), read_only(self) -> PsMemory<T>, revocable(self, &PsRevocation) -> PsMemory<T>; derefs to [T] and [T] mutably; Send and Sync; IntoPs hands the buffer to the engine as a Memory<T>, or a ReadOnlyMemory<T> after read_only (a T[] copy on .NET Framework).

PsMemoryView<T: Primitive>: unsafe writable<O: Send + Sync + 'static>(ptr: *mut T, len: usize, owner: O) -> PsMemoryView<T>, unsafe read_only<O: Send + Sync + 'static>(ptr: *const T, len: usize, owner: O) -> PsMemoryView<T>, revocable(self, &PsRevocation) -> PsMemoryView<T>, len(), is_empty(); Send and Sync; IntoPs hands the memory to the engine as a Memory<T> or ReadOnlyMemory<T> over it (a T[] copy on .NET Framework) and the owner with it, dropped when the view is released.

PsRevocation: new() -> PsRevocation, revoke(&self), is_revoked(&self) -> bool; Clone shares the flag, which is never cleared.

PsTask<T> (task.rs)

The argument a #[psmethods] method takes to return a Task<T> (a Task for PsTask<()>); see Attribute Reference . complete(self, value: T) where T: IntoPs, converting on the calling thread and faulting the task with the conversion’s error if it fails; fail(self, error: PsError); cancel(self); finish(self, result: PsResult<T>), which completes with the value or faults with the error; is_cancelled(&self) -> bool, a byte read that the caller’s CancellationToken sets. Send, so it moves to whatever thread does the work. Settling consumes it, so a task settles once; one dropped unsettled faults with PwrsTaskDropped. Continuations run asynchronously, never on the settling thread.

PsEvents (events.rs)

The engine events of a runspace, from Pipeline::events: Clone, Send and Sync, and it keeps the runspace’s event manager alive while it lives. See How To Raise Engine Events .

Both convert their values on the calling thread while holding attach_current_thread(), and a value that does not convert raises nothing and is the Err. The event is queued, or handed to the actions subscribed to it, before the call returns, so the events one thread raises arrive in the order raised; an action runs later on the runspace’s pipeline thread.

pwrs::thread (thread.rs)

For a thread the module starts to own a window, a COM object or anything else that belongs to one thread. See How To Use Threads .

PsType (dynamic.rs)

pwrs::dynamic::args_array(&[PsObject]) -> PsResult<PsObject> builds the object[] those calls pass.

PsHashtable, PsScriptBlock, PsBigInt, PsSecureString, PsCredential (types.rs)

PsHashtable(pub PsObject): new() -> PsResult<PsHashtable>, get(key) -> PsResult<PsObject>, set(key, value) -> PsResult<()>, contains(key) -> PsResult<bool>, len() -> PsResult<usize>, is_empty() -> PsResult<bool>, keys() -> PsResult<Vec<String>>.

PsScriptBlock(pub PsObject): call(&self, ps: &Pipeline<'_>, args: &[PsObject]) -> PsResult<Vec<PsObject>>.

PsBigInt { pub bytes: Vec<u8> }: little-endian two’s-complement; is_negative(), doubled().

PsSecureString(pub PsObject): new(text: &str) -> PsResult<PsSecureString>, len() -> PsResult<usize>, is_empty() -> PsResult<bool>, reveal() -> PsResult<String>.

PsCredential { pub user_name: String, pub password: PsSecureString }: new(user_name: &str, password: &str) -> PsResult<PsCredential>.

pwrs::types::display_string(&PsObject) -> PsResult<String> is String::from_ps.

HostUi (host_ui.rs)

$Host.UI of the cmdlet’s host, from Pipeline::host_ui. Every method is a dynamic member access on the pipeline thread, which is what a prompt costs next to the wait for a person. A host that cannot prompt, such as one run with -NonInteractive, refuses with the engine’s own error, and that is the Err.

PsDateTime, PsTimeSpan, PsGuid (values.rs)

PsDateTime { pub ticks: i64, pub kind: DateTimeKind }: new(ticks, kind), utc(ticks), to_utc() -> PsResult<PsDateTime>; TryFrom<SystemTime> and TryFrom<PsDateTime> for SystemTime. DateTimeKind is Unspecified, Utc or Local. Constants TICKS_PER_SECOND, UNIX_EPOCH_TICKS, MAX_DATETIME_TICKS.

PsTimeSpan { pub ticks: i64 }: from_ticks(ticks), is_negative(); TryFrom<Duration> and TryFrom<PsTimeSpan> for Duration; ordered.

PsGuid { pub bytes: [u8; 16] }: NIL, to_rfc4122() -> [u8; 16], from_rfc4122(bytes); Display and FromStr.

PsError and ErrorCategory (error.rs)

PsError { message, error_id, category, target: Option<PsObject>, terminating, details: Option<String> } with new(category, error_id, message), terminating(self), with_target(self, PsObject), with_details(self, text); From<std::io::Error>; Display as [id] message. Details reach the record’s Exception.InnerException on every path an error leaves by, a cmdlet’s record written or terminating and the exception a proxy method, static call, field read, provider, completer, transform or lifecycle hook throws, and the default error view still shows message alone. ErrorCategory has the 32 values of System.Management.Automation.ErrorCategory with the engine’s numeric values, and ErrorCategory::from_code(u32) -> Option<ErrorCategory> maps one back. PsResult<T> is Result<T, PsError>.

PsError is what a cmdlet raises. PsErrorRecord { category: ErrorCategory, error_id: String, message: String, target: PsObject } in values.rs is what a cmdlet reads: FromPs for a System.Management.Automation.ErrorRecord taken as a parameter or off the pipeline, from -ErrorVariable, from a catch, or from another command run through invoke. It is FromPs only; target is $null when the record carries none.

Cmdlet, CmdletMeta, CmdletBind (cmdlet.rs)

Cmdlet is the one you implement: process(&mut self, &Pipeline<'_>) -> PsResult<()> is required, begin and end have default bodies that mark the phase empty so the runtime stops calling them for that type.

CmdletMeta (the Verb-Noun name, the descriptor, the phase mask) and CmdletBind (bind, which reads the parameter block) are implemented by #[cmdlet] and #[param]. They are public because the generated code in your crate names them, not because a module writes them; writing either by hand is not supported.

TransformFn (transform.rs) and CompleterFn (completer.rs) are the same shape for #[transform] and #[completer]: the macro turns the function into a unit struct implementing the trait, and export_module! lists that struct.

Completion, CompletionContext, DynamicParam (completer.rs)

CompletionContext { word, command, bound: PsHashtable }. Completion { text, list_item, kind: CompletionKind, tooltip } with value(text) and with_tooltip(text). DynamicParam { name, clr_type, mandatory, position, set, help, validate_set } with string(name), mandatory(), with_validate_set(values).

Item, Drive, Provider (provider.rs)

Item { path, value, is_container } with leaf(path, value) and container(path, value); Drive { name, root }; the Provider trait’s methods are listed in How To Write A Provider : one value of the type serves one drive, made by default_drives() -> PsResult<Vec<(Drive, Self)>> or new_drive(name, root) -> PsResult<(Drive, Self)>, dropped after remove_drive(&mut self). pwrs::provider::child_name(path) is the last segment of a \- or /-separated path.

pwrs::testing and pwrs::trace

The fake host for unit tests and the counters are described in How To Test A Module and How To Trace A Module .