ABI Reference

The native contract, version 1. crates/pwrs-sys/src/lib.rs and crates/cargo-pwrs/dotnet/Pwrs.Runtime/HostVTable.cs describe the same memory and change in the same commit; docs/ABI.md in the repository is the normative copy of this page.

Rules

• Calling convention extern "C" everywhere; x64 and arm64.
• No unwinding across the boundary in either direction.
• Managed objects cross only as PsHandle (the IntPtr of a GCHandle) or as PsPinned views released before the phase returns.
• Strings cross as UTF-16 (ptr, len); readers size and retry.
• The table is append-only. The 8-byte header is size: u32, version: u32. At pwrs_module_init a module refuses, with status 4, a table whose size is smaller than the one it was compiled against or whose version differs, so it never calls through an entry the runtime lacks. version changes only when an existing entry changes meaning, and then the export names gain the major (pwrs2_*).

Status codes

Native exports

Phases: 0 Begin, 1 Process, 2 End. The phase mask reported by pwrs_cmdlet_create has bit 1 for Begin, 2 for Process, 4 for End; it starts at 7 and loses a bit once the runtime has seen that phase run the trait’s default body for the type.

Host vtable

Slot order is declaration order. “pipeline” entries return status 3 off the pipeline thread.

Memory views with an owner

memory_view_borrow(tag, ptr, len, read_only, refused, context, release, out, err) wraps len elements of the primitive tag at ptr as a Memory<T>, or a ReadOnlyMemory<T> when read_only is nonzero, over that memory on .NET, and copies them into a T[] on .NET Framework. On success the host takes context and calls release(context) exactly once: when the view’s manager is disposed or finalized on .NET, and before the entry returns on .NET Framework. On failure it has not called release and never will. refused, when not null, points at a byte the module sets nonzero to refuse the view, readable until release runs; the host reads it when the view is made and on .NET before every GetSpan and Pin, and a refusal is an ObjectDisposedException, as is GetSpan or Pin on a disposed manager. memory_view_new(tag, ptr, len, drop_fn, out, err) is this entry with ptr as the context, writable and never refused. PsMemory<T> and PsMemoryView<T> cross through it; see the Pipeline Reference .

Tasks

A #[psmethods] argument of slot task is a PsTaskSlot { source: PsHandle, cancelled: *const u8 }: a handle to the Pwrs.TaskSource<T> the generated method made, which holds a TaskCompletionSource<T> created with RunContinuationsAsynchronously and listens to the caller’s CancellationToken, and a byte the token’s callback sets nonzero. task_settle(source, outcome, value, err) settles it: 0 with value the result (null for a task of no value), 1 faulted with value the handle a failing export hands back (an exception, or a string [id] message, thrown as a PwrsException), 2 canceled with the caller’s token. The first settle wins; it disposes the token’s registration, waiting for a callback another thread is running, and only then frees the byte. A call that throws before Rust takes the task faults it with the same exception.

Engine events

event_raise(events, source_identifier, sender, args, message_data, err) raises an engine event through events, a handle to a PSEventManager, with the arguments New-Event passes to GenerateEvent: sender and args as their base objects, args as an object[] of an array’s elements (empty for null, the one value for anything else), message_data as a PSObject (null for none), processed on the calling thread without waiting for its actions. The event is queued, or handed to the actions subscribed to it, before the entry returns, so the events one thread raises keep their order; an action runs later on the runspace’s pipeline thread. The handles stay the caller’s. Pipeline::events reads the manager off the cmdlet’s Events through dyn_get. See How To Raise Engine Events .

Strings read in place

string_pin(h, out, err) converts h to a string as string_read does and pins that string where it lies: out takes the address of its first UTF-16 unit, its length in units, an element size of 2 and the pin. The units are read, never written, and the pin is released with array_unpin before the phase that pinned it returns. String::from_ps reads a string of up to 256 units through string_read into a buffer of that size, and a longer one through string_pin, transcoding the pinned units with no copy between.

Progress records with every field

write_progress_record(cmdlet, activity_id, parent_activity_id, activity, status, current_operation, percent, seconds_remaining, completed, err) writes a ProgressRecord with every field set. It is the completing record when completed is nonzero and a processing one otherwise, so a processing record can carry a negative percent, which shows none. A percent above 100 is 100, a negative parent_activity_id leaves the activity unnested, a negative seconds_remaining shows no time left, and an empty current_operation sets none. The engine refuses an empty activity or status, a negative activity id, and a parent activity id equal to the activity id; that refusal comes back through err. write_progress keeps its meaning: a negative percent there writes the completing record. Pipeline::write_progress and Worker::write_progress are the Rust surface over it; see the Pipeline Reference .

Errors that carry details

write_error_details(cmdlet, message, error_id, category, target, terminating, details, err) is write_error for a PsError with details: the record’s exception has message as its Message and an inner exception whose Message is details, so the default error view shows the one line and $err.Exception.InnerException.Message holds the rest. exception_new(message, details) answers a handle to such an exception. An export that fails hands it back through err in place of the [id] message string, and every call site throws an exception it finds there as it is, so a proxy method’s, a static call’s, a field read’s, a provider’s, a completer’s, a transform’s and a lifecycle hook’s error carries its details too; PowerShell wraps a method’s exception in a MethodInvocationException, one level further in. An error without details takes write_error and the string.

Helper executables

helper_path(name, buf, cap, out_len, err) answers where to start a helper executable the module ships in runtimes/<rid>/native/, name being its file name without .exe. The first request for a helper’s bytes copies it into the folder the process stages the module’s library in, at native/<file>.<mark>/<file>, where the mark is the shipped file’s write time and length in hex; every later request answers the same path. The copy is written under a temporary name and moved into place, so no caller is answered a file another thread is still writing. The path is copied into buf like string_read’s. A name that is not a bare file name, and a helper the module does not ship, are the status. On Windows PowerShell each module’s own table answers this entry, as it answers factory_new. pwrs::helper_path is the Rust surface over it; see How To Ship A Helper Executable .

Typed values

| object_type_tag(h, out_tag, err) | the tag of one object’s own type, PS_TYPE_OBJECT for a type outside the vocabulary; unwraps a PSObject first, so a wrapped Int32 answers PS_TYPE_I32 | | i8_new, i16_new, i32_new, u8_new, u16_new, u32_new, f32_new | each builds the CLR type of its own name instead of widening to Int64 or Double | | decimal_new(lo, mid, hi, flags, out, err), decimal_read(h, out_bits, err) | the four words in Decimal.GetBits order, which is not their order in memory; decimal_new rejects a scale above 28 or reserved bits set | | datetimeoffset_new(ticks, offset_minutes, out, err), datetimeoffset_read(h, out_ticks, out_offset_minutes, err) | ticks of 100 ns from the start of year 1, and the UTC offset in whole minutes | | enum_new(type_name, value, out, err) | a value of the CLR enum type_name names, from its underlying number, through Enum.ToObject. The name is resolved with LanguagePrimitives.ConvertTo<Type>, the same resolver a type literal uses, and a name it cannot reach or a type that is not an enum is the status. A module’s own #[psenum] types go through factory_new instead, which needs no name | | proxy_enter(obj, class_id, out_instance, err), proxy_enter_shared(obj, class_id, out_instance, err), proxy_exit(obj, changed) | lend a proxy’s value to native code under the object’s gate, the one its property reads and method calls take. Both enter forms check that obj is a live proxy of the calling module’s class class_id from the current load. proxy_enter is the exclusive entry with_mut makes, refused while anything is inside the object on the calling thread and refusing everything while it lasts, as a &mut self method is; proxy_enter_shared is the shared entry with makes, which nests inside a &self method, a property read or another shared entry and is refused only inside an exclusive one. proxy_exit releases the entry, and with changed nonzero asks a native_bytes class for its bytes again. On Windows PowerShell each module’s own table answers both enter forms, as it answers factory_new | | invoke_command(cmdlet, name, parameters, input, out, err) | runs name in a nested PowerShell in the current runspace, added by name, so the engine resolves it as it does a typed command and a module’s function runs in its module’s scope, parameters an IDictionary bound by name or null, input piped in or null (a collection unrolled, a string or other single value one record); out receives an object[] of everything it wrote. The command’s non-terminating errors are written to the calling cmdlet’s error stream; a terminating one, and an unknown name, are the status. Pipeline thread |

Type tags 14, 15 and 16 (DateTime, TimeSpan, Guid) join the primitive tags array_new accepts, so a Vec of those types becomes a typed array; such arrays are not pinnable.

Tag 17 (Decimal) is accepted by array_new and, unlike those three, its arrays ARE pinnable: Type.IsPrimitive is false for System.Decimal but it is blittable and pins, so array_pin admits it by name. A pinned element is PsDecimalBits, the four words in memory order, and the first such pin in a process checks that order against Decimal.GetBits before any element is read.

Parameter block

Per cmdlet, a #[repr(C)] struct on both sides: dirty: u64, bound: u64, then one slot per parameter in declaration order. Bit i of bound is set when parameter i was ever assigned; bit i of dirty when it was assigned since the previous phase. The generated property setters maintain both. The native side binds before the first phase and again only when dirty is non-zero, and leaves a parameter whose bound bit is clear at its field’s value. Slots: u8 for switches, the numeric types at their width, PsStr16 for strings (pinned fixed for the call), PsHandle for arrays, objects, class objects, script blocks, hashtables, secure strings, credentials and boxed value types (enums, DateTime, TimeSpan, Guid, char), a GCHandle allocated for the call and freed after. The block lives on the managed stack for one phase; the Rust reader clones handles before keeping them.

Class field block

Copied classes pack one slot per field in the same way, followed by mask: u64 with a bit per Option field that is Some; factory_new(class_id, &block) hands it to the registered factory, which unboxes value-typed handles with a cast and converts array-typed ones with LanguagePrimitives.ConvertTo to the declared element type. Proxy classes pass the boxed instance pointer instead. Enums pass a single i64.

A class id is its class’s position in its own module’s export_module! list, so it names a class only within one module, and each module’s factories are a table of their own. A type finds its id by its Rust type, through the entry’s type_id, never by its name: a type the list does not carry has no id even when a listed type carries its name, and its write is refused with PwrsClassNameTaken, naming both. Each type’s id lookup also holds a record, PWRS-CLASS/1, a tab, its name, a tab, its Rust path, then NUL, so a library carries one for every class whose values it can write, listed or not, and cargo pwrs build reads them out of the file to refuse a type under a name another type carries. On PowerShell 7 every module has a copy of Pwrs.Runtime to itself, so factory_new in the one host table reads that copy’s table. On Windows PowerShell one copy serves every module in the process, so each module’s library is handed its own copy of the host table, identical except for factory_new, which answers from that module’s table; the shared table’s factory_new refuses there, since no module is handed it. Pwrs.NativeModule.FactoriesPerModule is true on a runtime that works this way and absent on one that does not.

Method block

A #[psmethods] method on a proxy class receives bound: u64 then one slot per argument in declaration order, packed by the generated C# method with the slot rules of a parameter block; bit i of bound is set when argument i was supplied. pwrs_proxy_call returns the result as a handle (null for ()); an Err is status 1 with the message, thrown to the script as a PwrsException. The managed base serializes calls and property reads on one object.

An argument of slot peer is another object of the same class, a &Self argument in Rust, and its slot is a pointer: the generated method refuses a null object, enters that object’s gate as shared beside the receiver’s, both in the order the two objects were made, and writes the other object’s value pointer into the slot. A method has at most one, and only a method with a receiver has one. An argument of slot task is a PsTaskSlot; see Tasks . A class’s descriptor may name the methods behind the .NET interfaces its generated class implements (count, item, set_item, next, compare, equals, hash), and each interface member calls the method its key names.

Provider drives

A provider operation carries the pointer of the Rust instance serving the current drive. The drive-making operations (INIT_DEFAULT_DRIVES, NEW_DRIVE) take null and return rows [name, root, instance] whose pointers the managed PwrsDriveInfo keeps; the path operations ignore the pointer; every other operation needs it and fails with PwrsProviderNoDrive when the engine resolved no drive of the provider. REMOVE_DRIVE runs remove_drive and frees the instance on Ok; DROP_DRIVE frees it without running remove_drive, for a drive the engine collected without removing. Operations on one drive are serialized by the managed drive object.

Error flow through a phase

A body Err is written through write_error before pwrs_cmdlet_invoke returns: non-terminating records go to WriteError at once; a terminating record is stored on the managed cmdlet and raised with ThrowTerminatingError after the native call returns. A PipelineStoppedException inside any entry marks the cmdlet stopped and returns status 5; the managed Invoke rethrows it after the native call. A panic in a phase returns status 2 and the managed side raises a terminating PwrsNativePanic error with the message.