PDComm.GemHostWorker

Class

A GEM host endpoint that runs on a dedicated polling thread and exposes asynchronous commands.

public sealed class GemHostWorker : GemWorker

The worker creates a GemHost on its thread, starts the transport, and delivers every processed event through GemWorker.ReadEventsAsync. A request command completes with the request token once the message is sent; the reply arrives later as a GemEvent whose result carries the same GemResultInfo.Token.

Each *Async command queues the synchronous GemHost method of the same name on the worker thread; see GemWorker for queueing, backpressure and shutdown rules.

await using GemHostWorker host = await GemHostWorker.StartAsync(address, transportOptions,
    new GemHostOptions { MaxPendingIds = 64, ItemLimits = limits }, workerOptions, cancellationToken);
await using IAsyncEnumerator<GemEvent> events = host.ReadEventsAsync(cancellationToken).GetAsyncEnumerator();
bool began = false;
HsmsToken pending = default;
while (true)
{
    if (!began && (await host.GetTransportStateAsync(cancellationToken)).State == HsmsConnectionState.Selected)
    {
        pending = await host.BeginCommunicationAsync(cancellationToken);
        began = true;
    }
    if (!await events.MoveNextAsync()) break;
    using GemEvent current = events.Current;
    GemResultInfo? info = current.Result?.GetInfo();
    if (info is not { Kind: GemResultKind.Response } || info.Value.Token != pending) continue;
    if (info.Value.Outcome == GemOutcome.CommunicationEstablished)
        pending = await host.RequestStatusValuesAsync(new uint[] { 1, 2 }, cancellationToken);
    else if (info.Value.Outcome == GemOutcome.ValuesReceived)
        break;
}
await host.StopAsync(cancellationToken);
while (await events.MoveNextAsync()) events.Current.Dispose();
await host.Completion;

Members

`AcknowledgeAlarmAsync`

Method

Queues GemHost.AcknowledgeAlarm on the worker thread.

public Task AcknowledgeAlarmAsync(GemResult result, byte acknowledgement, CancellationToken cancellationToken = default)

The worker keeps the native result alive until the command finishes, and reserves one message of GemHostOptions.ItemLimits in the command byte budget.

Parameters

Name	Description
`result`	The result of the received S5F1 alarm report whose W-bit is set.
`acknowledgement`	The acknowledge code (ACKC5), 0 through 63. 0 means accepted.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes when the S5F2 reply was accepted for sending. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full, or when the command runs while event output is blocked), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.AcknowledgeAlarm.

Notes

Throws ArgumentNullException: result is null.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws ObjectDisposedException: result was disposed.

`AcknowledgeEventAsync`

Method

Queues GemHost.AcknowledgeEvent on the worker thread.

public Task AcknowledgeEventAsync(GemResult result, byte acknowledgement, CancellationToken cancellationToken = default)

The queued command keeps the result's native handle alive until it completes, so the caller can dispose result (or the GemEvent that holds it) after this method returns. The command reserves the host's message byte limit (SecsLimits.MessageBytes of the item limits) from the worker's command byte budget. It runs on the worker's polling thread, which owns the endpoint. The task is canceled when cancellationToken is canceled before the command runs. It faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when event output is blocked as the command runs, with ObjectDisposedException after the worker stopped accepting commands, and otherwise with the exception of GemHost.AcknowledgeEvent.

Parameters

Name	Description
`result`	The result of a received S6F11, whose outcome is `GemOutcome.EventReceived`.
`acknowledgement`	The acknowledge code (ACKC6), 0 to 63; 0 means accepted.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes when S6F12 was sent.

Notes

Throws ArgumentNullException: result is null.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws ObjectDisposedException: result was disposed.

`AreYouOnlineAsync`

Method

Queues GemHost.AreYouOnline on the worker thread to send S1F1 (Are You There).

public Task<HsmsToken> AreYouOnlineAsync(CancellationToken cancellationToken = default)

The command runs on the worker thread, which owns the endpoint. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or its byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, and is canceled when cancellationToken is canceled before the command runs. Otherwise it carries any exception of GemHost.AreYouOnline.

Parameters

Name	Description
`cancellationToken`	A token that cancels the command if it has not run yet.

Returns

A task that completes with the token of the request once it is sent.

`CancelProgramGrantAsync`

Method

Queues GemHost.CancelProgramGrant on the worker thread.

public Task CancelProgramGrantAsync(GemResult result, CancellationToken cancellationToken = default)

result stays valid until the command finishes, even if you dispose it meanwhile. The command reserves SecsLimits.MessageBytes of the GEM item limits of the command byte budget.

Parameters

Name	Description
`result`	The original S7F1 request result whose reply granted the program.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes when the grant was withdrawn. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.CancelProgramGrant.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: result was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store.

`ChangeConstantsAsync`

Method

Queues GemHost.ChangeConstants on the worker thread.

public Task<HsmsToken> ChangeConstantsAsync(ReadOnlyMemory<GemConstantChange> changes, CancellationToken cancellationToken = default)

The S2F16 reply arrives later as an event with the same token. The encoded items count against the command byte budget.

Parameters

Name	Description
`changes`	The ECID/ECV pairs in request order. Their items are encoded before the method returns, so the caller may dispose them afterward.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the token of the S2F15 request. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.ChangeConstants.

Notes

Throws ArgumentNullException: A change, or its ID or value, is null.
Throws ObjectDisposedException: An item of a change was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.LimitExceeded when an item or the request message exceeds GemHostOptions.ItemLimits; PdcommStatus.Backpressure when the memory behind changes was modified while it was copied.

`ConfirmProgramReplyAsync`

Method

Queues GemHost.ConfirmProgramReply on the worker thread.

public Task ConfirmProgramReplyAsync(GemResult result, CancellationToken cancellationToken = default)

result stays valid until the command finishes, even if you dispose it meanwhile. The command reserves SecsLimits.MessageBytes of the GEM item limits of the command byte budget.

Parameters

Name	Description
`result`	The received S7F3 or S7F17 request whose installation is unconfirmed.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes when the saved reply is ready to be sent with GemHostWorker.RespondProgramAsync. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.ConfirmProgramReply.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: result was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store.

`DefineReportsAsync`

Method

Queues GemHost.DefineReports on the worker thread.

public Task<HsmsToken> DefineReportsAsync(uint dataId, ReadOnlyMemory<GemReportSpec> specs, CancellationToken cancellationToken = default)

The command runs on the worker's polling thread, which owns the endpoint. The task is canceled when cancellationToken is canceled before the command runs. It faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when event output is blocked as the command runs, with ObjectDisposedException after the worker stopped accepting commands, and otherwise with the exception of GemHost.DefineReports. The equipment's S2F34 arrives later as a GemEvent from GemWorker.ReadEventsAsync.

Parameters

Name	Description
`dataId`	The data ID (DATAID) of the S2F33 request.
`specs`	The reports to define. An empty memory asks the equipment to delete all reports and their links. The worker copies the specifications before this method returns.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the token of the pending S2F33/S2F34 transaction.

Notes

Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.LimitExceeded when the total number of report and variable IDs exceeds the host's item count limit or the number of 4-byte IDs that fit the message byte limit.

`DeleteProgramsAsync`

Method

Queues GemHost.DeletePrograms on the worker thread.

public Task<HsmsToken> DeleteProgramsAsync(ReadOnlyMemory<SecsItem> ids, CancellationToken cancellationToken = default)

The encoded PPIDs count against the command byte budget.

Parameters

Name	Description
`ids`	The PPIDs to delete on the equipment, or empty to delete every program. They are encoded before the method returns, so the caller may dispose them afterward.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the token of the S7F17 request. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.DeletePrograms.

Notes

Throws ArgumentNullException: An ID is null.
Throws ObjectDisposedException: An ID was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store; PdcommStatus.InvalidArgument when a PPID is empty or not an ASCII or binary item; PdcommStatus.LimitExceeded when an item exceeds the GEM item limits, a PPID is longer than GemProgramOptions.MaxIdentifierBytes or 120 bytes, ids has more entries than GemProgramOptions.MaxRequestIds or GemProgramOptions.MaxPendingIds, or the PPIDs together are longer than GemProgramOptions.MaxPendingIdentifierBytes.

`EnableAlarmAsync`

Method

Queues GemHost.EnableAlarm on the worker thread.

public Task<HsmsToken> EnableAlarmAsync(uint id, bool enabled, bool replyExpected, CancellationToken cancellationToken = default)

Parameters

Name	Description
`id`	The alarm ID (ALID).
`enabled`	`true` to enable reporting of the alarm; `false` to disable it.
`replyExpected`	`true` to set the W-bit and expect an S5F4 (Enable/Disable Alarm Acknowledge) reply.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the transport token of the S5F3 request. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full, or when the command runs while event output is blocked), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.EnableAlarm.

`EnableEventsAsync`

Method

Queues GemHost.EnableEvents on the worker thread.

public Task<HsmsToken> EnableEventsAsync(bool enabled, ReadOnlyMemory<uint> eventIds, CancellationToken cancellationToken = default)

The command runs on the worker's polling thread, which owns the endpoint. The task is canceled when cancellationToken is canceled before the command runs. It faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when event output is blocked as the command runs, with ObjectDisposedException after the worker stopped accepting commands, and otherwise with the exception of GemHost.EnableEvents. The equipment's S2F38 arrives later as a GemEvent from GemWorker.ReadEventsAsync.

Parameters

Name	Description
`enabled`	The collection event enable/disable flag (CEED): `true` to enable, `false` to disable.
`eventIds`	The collection event IDs (CEIDs) to change, or empty for all events. The worker copies the IDs before this method returns.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the token of the pending S2F37/S2F38 transaction.

Notes

Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.LimitExceeded when the number of event IDs exceeds the host's item count limit or the number of 4-byte IDs that fit the message byte limit.

`EnhancedRemoteCommandAsync`

Method

Queues GemHost.EnhancedRemoteCommand on the worker thread.

public Task<HsmsToken> EnhancedRemoteCommandAsync(uint dataId, SecsItem objectName, SecsItem name, ReadOnlyMemory<GemCommandParameter> parameters, CancellationToken cancellationToken = default)

The command reserves the encoded size of the snapshot in the command byte budget.

Parameters

Name	Description
`dataId`	The data ID (DATAID).
`objectName`	The object specifier (OBJSPEC): an ASCII item.
`name`	The remote command name (RCMD): a nonempty ASCII item or a scalar integer item.
`parameters`	The command parameters (CPNAME and CEPVAL). The items are encoded into a snapshot before the method returns.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the transport token of the S2F49 request. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full, or when the command runs while event output is blocked), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.EnhancedRemoteCommand.

Notes

Throws ArgumentNullException: objectName, name, a parameter, or a parameter name or value is null.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws ObjectDisposedException: One of the items was disposed.
Throws PdcommException: PdcommStatus.LimitExceeded when the parameter count, an item, or the combined encoded size of the items exceeds GemHostOptions.ItemLimits.

`GetProgramAsync`

Method

Queues GemHost.GetProgram on the worker thread.

public Task<SecsItem> GetProgramAsync(SecsItem id, CancellationToken cancellationToken = default)

The encoded PPID counts against the command byte budget.

Parameters

Name	Description
`id`	The process program ID (PPID): a nonempty ASCII or binary item. It is encoded before the method returns, so the caller may dispose it afterward.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with a new body item that the caller owns and must dispose. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.GetProgram.

Notes

Throws ArgumentNullException: id is null.
Throws ObjectDisposedException: id was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store; PdcommStatus.InvalidArgument when the PPID is empty or not an ASCII or binary item; PdcommStatus.LimitExceeded when an item exceeds the GEM item limits, the PPID is longer than GemProgramOptions.MaxIdentifierBytes or 120 bytes.

`GetProgramAtAsync`

Method

Queues GemHost.GetProgramAt on the worker thread.

public Task<GemProgramEntry> GetProgramAtAsync(nuint index, CancellationToken cancellationToken = default)

Parameters

Name	Description
`index`	The zero-based position in the store.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with a new entry that the caller owns and must dispose. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.GetProgramAt.

Notes

Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store.

`GetProgramStateAsync`

Method

Queues GemHost.GetProgramState on the worker thread.

public Task<GemProgramState> GetProgramStateAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the process program store counters. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.GetProgramState.

Notes

Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store.

`GrantProgramAsync`

Method

Queues GemHost.GrantProgram on the worker thread.

public Task<HsmsToken> GrantProgramAsync(SecsItem id, uint length, CancellationToken cancellationToken = default)

The encoded PPID counts against the command byte budget.

Parameters

Name	Description
`id`	The process program ID (PPID): a nonempty ASCII or binary item. It is encoded before the method returns, so the caller may dispose it afterward.
`length`	The length in bytes of the body payload that will be sent (LENGTH).
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the token of the S7F1 request. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.GrantProgram.

Notes

Throws ArgumentNullException: id is null.
Throws ObjectDisposedException: id was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store; PdcommStatus.InvalidArgument when the PPID is empty or not an ASCII or binary item; PdcommStatus.LimitExceeded when an item exceeds the GEM item limits, the PPID is longer than GemProgramOptions.MaxIdentifierBytes or 120 bytes or, because the request stays pending, when GemProgramOptions.MaxPendingIds is 0 or the PPID is longer than GemProgramOptions.MaxPendingIdentifierBytes.

`LinkReportsAsync`

Method

Queues GemHost.LinkReports on the worker thread.

public Task<HsmsToken> LinkReportsAsync(uint dataId, ReadOnlyMemory<GemLinkSpec> specs, CancellationToken cancellationToken = default)

The command runs on the worker's polling thread, which owns the endpoint. The task is canceled when cancellationToken is canceled before the command runs. It faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when event output is blocked as the command runs, with ObjectDisposedException after the worker stopped accepting commands, and otherwise with the exception of GemHost.LinkReports. The equipment's S2F36 arrives later as a GemEvent from GemWorker.ReadEventsAsync.

Parameters

Name	Description
`dataId`	The data ID (DATAID) of the S2F35 request.
`specs`	The event links to add. An event with no report IDs asks the equipment to unlink all reports from that event. The worker copies the specifications before this method returns.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the token of the pending S2F35/S2F36 transaction.

Notes

Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.LimitExceeded when the total number of event and report IDs exceeds the host's item count limit or the number of 4-byte IDs that fit the message byte limit.

`QueryRemoteSpoolingAsync`

Method

Queues GemHost.QueryRemoteSpooling on the worker thread.

public Task<HsmsToken> QueryRemoteSpoolingAsync(CancellationToken cancellationToken = default)

The S2F60 reply arrives through GemWorker.ReadEventsAsync.

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the transport token of the S2F59 request. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full, or when the command runs while event output is blocked), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.QueryRemoteSpooling.

Notes

Throws PdcommException: PdcommStatus.InvalidState when the worker was not started with GemHostWorker.StartWithSpoolingAsync.

`RemoteCommandAsync`

Method

Queues GemHost.RemoteCommand on the worker thread.

public Task<HsmsToken> RemoteCommandAsync(SecsItem name, ReadOnlyMemory<GemCommandParameter> parameters, CancellationToken cancellationToken = default)

The command reserves the encoded size of the snapshot in the command byte budget.

Parameters

Name	Description
`name`	The remote command name (RCMD): a nonempty ASCII item or a scalar integer item.
`parameters`	The command parameters (CPNAME and CPVAL). The items are encoded into a snapshot before the method returns.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the transport token of the S2F41 request. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full, or when the command runs while event output is blocked), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.RemoteCommand.

Notes

Throws ArgumentNullException: name, a parameter, or a parameter name or value is null.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws ObjectDisposedException: One of the items was disposed.
Throws PdcommException: PdcommStatus.LimitExceeded when the parameter count, an item, or the combined encoded size of the items exceeds GemHostOptions.ItemLimits.

`RequestAlarmListAsync`

Method

Queues GemHost.RequestAlarmList on the worker thread.

public Task<HsmsToken> RequestAlarmListAsync(ReadOnlyMemory<uint> ids, CancellationToken cancellationToken = default)

Parameters

Name	Description
`ids`	The alarm IDs (ALID) to list, or an empty memory to list every alarm. The IDs are copied before the method returns.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the transport token of the S5F5 request. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full, or when the command runs while event output is blocked), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.RequestAlarmList.

Notes

Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.LimitExceeded when the number of IDs exceeds GemHostOptions.MaxPendingIds, the item count of GemHostOptions.ItemLimits, or the number of 4-byte IDs that fit in its message size.

`RequestAnnotatedQueryAsync`

Method

Queues GemHost.RequestAnnotatedQuery on the worker thread to send S6F21.

public Task<HsmsToken> RequestAnnotatedQueryAsync(uint id, CancellationToken cancellationToken = default)

See GemHostWorker.RequestReportQueryAsync. The command runs on the worker thread, which owns the endpoint. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or its byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, and is canceled when cancellationToken is canceled before the command runs. Otherwise it carries any exception of GemHost.RequestAnnotatedQuery.

Parameters

Name	Description
`id`	The report ID (RPTID).
`cancellationToken`	A token that cancels the command if it has not run yet.

Returns

A task that completes with the token of the request once it is sent.

Notes

Throws PdcommException: PdcommStatus.LimitExceeded when GemHostOptions.MaxPendingIds is zero.
Throws OperationCanceledException: cancellationToken is already canceled.

`RequestConstantMetadataAsync`

Method

Queues GemHost.RequestConstantMetadata on the worker thread.

public Task<HsmsToken> RequestConstantMetadataAsync(ReadOnlyMemory<SecsItem> ids, CancellationToken cancellationToken = default)

The reply arrives later as an event with the same token. The encoded IDs count against the command byte budget.

Parameters

Name	Description
`ids`	The equipment constant IDs (ECIDs), or empty to request every constant. They are encoded before the method returns, so the caller may dispose them afterward.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the token of the request. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.RequestConstantMetadata.

Notes

Throws ArgumentNullException: An ID is null.
Throws ObjectDisposedException: An ID was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.LimitExceeded when ids has more entries than GemHostOptions.MaxPendingIds, or an ID or the request message exceeds GemHostOptions.ItemLimits; PdcommStatus.Backpressure when the memory behind ids was modified while it was copied.

`RequestConstantValuesAsync`

Method

Queues GemHost.RequestConstantValues on the worker thread.

public Task<HsmsToken> RequestConstantValuesAsync(ReadOnlyMemory<SecsItem> ids, CancellationToken cancellationToken = default)

The reply arrives later as an event with the same token. The encoded IDs count against the command byte budget.

Parameters

Name	Description
`ids`	The equipment constant IDs (ECIDs), or empty to request every constant. They are encoded before the method returns, so the caller may dispose them afterward.
`cancellationToken`	The token that cancels the command before it runs.

Returns

Notes

Throws ArgumentNullException: An ID is null.
Throws ObjectDisposedException: An ID was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.LimitExceeded when ids has more entries than GemHostOptions.MaxPendingIds, or an ID or the request message exceeds GemHostOptions.ItemLimits; PdcommStatus.Backpressure when the memory behind ids was modified while it was copied.

`RequestDirectoryAsync`

Method

Queues GemHost.RequestDirectory on the worker thread.

public Task<HsmsToken> RequestDirectoryAsync(GemDirectoryKind kind, ReadOnlyMemory<uint> ids, CancellationToken cancellationToken = default)

The command runs on the worker's polling thread, which owns the endpoint. The task is canceled when cancellationToken is canceled before the command runs. It faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when event output is blocked as the command runs, with ObjectDisposedException after the worker stopped accepting commands, and otherwise with the exception of GemHost.RequestDirectory. The equipment's reply arrives later as a GemEvent from GemWorker.ReadEventsAsync.

Parameters

Name	Description
`kind`	The directory to request.
`ids`	The VIDs or CEIDs to request, or empty for all entries. The worker copies the IDs before this method returns.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the token of the pending namelist transaction.

Notes

Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidArgument when kind is not a defined value, or PdcommStatus.LimitExceeded when ids has more entries than GemHostOptions.MaxPendingIds or the request would exceed the host's item limits.

`RequestEnabledAlarmListAsync`

Method

Queues GemHost.RequestEnabledAlarmList on the worker thread.

public Task<HsmsToken> RequestEnabledAlarmListAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the transport token of the S5F7 request. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full, or when the command runs while event output is blocked), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.RequestEnabledAlarmList.

`RequestEventQueryAsync`

Method

Queues GemHost.RequestEventQuery on the worker thread to send S6F15.

public Task<HsmsToken> RequestEventQueryAsync(uint id, CancellationToken cancellationToken = default)

Parameters

Name	Description
`id`	The collection event ID (CEID).
`cancellationToken`	A token that cancels the command if it has not run yet.

Returns

A task that completes with the token of the request once it is sent.

Notes

Throws PdcommException: PdcommStatus.LimitExceeded when GemHostOptions.MaxPendingIds is zero.
Throws OperationCanceledException: cancellationToken is already canceled.

`RequestIndividualQueryAsync`

Method

Queues GemHost.RequestIndividualQuery on the worker thread to send S6F19.

public Task<HsmsToken> RequestIndividualQueryAsync(uint id, CancellationToken cancellationToken = default)

Parameters

Name	Description
`id`	The report ID (RPTID).
`cancellationToken`	A token that cancels the command if it has not run yet.

Returns

A task that completes with the token of the request once it is sent.

Notes

Throws PdcommException: PdcommStatus.LimitExceeded when GemHostOptions.MaxPendingIds is zero.
Throws OperationCanceledException: cancellationToken is already canceled.

`RequestOfflineAsync`

Method

Queues GemHost.RequestOffline on the worker thread to send S1F15 (Request Off-line).

public Task<HsmsToken> RequestOfflineAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	A token that cancels the command if it has not run yet.

Returns

A task that completes with the token of the request once it is sent.

`RequestOnlineAsync`

Method

Queues GemHost.RequestOnline on the worker thread to send S1F17 (Request On-line).

public Task<HsmsToken> RequestOnlineAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	A token that cancels the command if it has not run yet.

Returns

A task that completes with the token of the request once it is sent.

`RequestProgramAsync`

Method

Queues GemHost.RequestProgram on the worker thread.

public Task<HsmsToken> RequestProgramAsync(SecsItem id, CancellationToken cancellationToken = default)

The encoded PPID counts against the command byte budget.

Parameters

Name	Description
`id`	The process program ID (PPID): a nonempty ASCII or binary item. It is encoded before the method returns, so the caller may dispose it afterward.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the token of the S7F5 request. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.RequestProgram.

Notes

Throws ArgumentNullException: id is null.
Throws ObjectDisposedException: id was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store; PdcommStatus.InvalidArgument when the PPID is empty or not an ASCII or binary item; PdcommStatus.LimitExceeded when an item exceeds the GEM item limits, the PPID is longer than GemProgramOptions.MaxIdentifierBytes or 120 bytes or, because the request stays pending, when GemProgramOptions.MaxPendingIds is 0 or the PPID is longer than GemProgramOptions.MaxPendingIdentifierBytes.

`RequestProgramDirectoryAsync`

Method

Queues GemHost.RequestProgramDirectory on the worker thread.

public Task<HsmsToken> RequestProgramDirectoryAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the token of the S7F19 request. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.RequestProgramDirectory.

Notes

Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store.

`RequestReportQueryAsync`

Method

Queues GemHost.RequestReportQuery on the worker thread to send an S6 report query.

public Task<HsmsToken> RequestReportQueryAsync(GemReportQueryKind kind, uint id, CancellationToken cancellationToken = default)

Parameters

Name	Description
`kind`	The query: S6F15 for `GemReportQueryKind.Event`, S6F19 for `GemReportQueryKind.Individual`, S6F21 for `GemReportQueryKind.Annotated`.
`id`	The collection event ID (CEID) for an event query, otherwise the report ID (RPTID).
`cancellationToken`	A token that cancels the command if it has not run yet.

Returns

A task that completes with the token of the request once it is sent.

Notes

Throws PdcommException: PdcommStatus.InvalidArgument for an undefined kind; PdcommStatus.LimitExceeded when GemHostOptions.MaxPendingIds is zero.
Throws OperationCanceledException: cancellationToken is already canceled.

`RequestSpoolConfigurationAsync`

Method

Queues GemHost.RequestSpoolConfiguration on the worker thread.

public Task<HsmsToken> RequestSpoolConfigurationAsync(ReadOnlyMemory<GemSpoolSelection> selections, CancellationToken cancellationToken = default)

The S2F44 reply arrives through GemWorker.ReadEventsAsync.

Parameters

Name	Description
`selections`	The streams to spool; an empty function list requests every function of the stream. They are copied before this method returns, and each stream with its functions counts against the command byte budget.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the transport token of the S2F43 request. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full, or when the command runs while event output is blocked), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.RequestSpoolConfiguration.

Notes

Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was not started with GemHostWorker.StartWithSpoolingAsync; PdcommStatus.LimitExceeded when the selections exceed GemSpoolHostOptions.MaxStreams or GemSpoolHostOptions.MaxFunctionsPerStream.

`RequestSpooledDataAsync`

Method

Queues GemHost.RequestSpooledData on the worker thread.

public Task<HsmsToken> RequestSpooledDataAsync(GemSpoolCommand command, CancellationToken cancellationToken = default)

The S6F24 reply arrives through GemWorker.ReadEventsAsync.

Parameters

Name	Description
`command`	The request spooled data code (RSDC).
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the transport token of the S6F23 request. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full, or when the command runs while event output is blocked), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.RequestSpooledData.

Notes

Throws ArgumentOutOfRangeException: command is not a defined GemSpoolCommand value.
Throws PdcommException: PdcommStatus.InvalidState when the worker was not started with GemHostWorker.StartWithSpoolingAsync.

`RequestStatusNamesAsync`

Method

Queues GemHost.RequestStatusNames on the worker thread to send S1F11 for status variable names and units.

public Task<HsmsToken> RequestStatusNamesAsync(ReadOnlyMemory<uint> ids, CancellationToken cancellationToken = default)

The IDs are copied before the method returns; each ID counts 4 bytes against the command byte budget. The command runs on the worker thread, which owns the endpoint. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or its byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, and is canceled when cancellationToken is canceled before the command runs. Otherwise it carries any exception of GemHost.RequestStatusNames.

Parameters

Name	Description
`ids`	The status variable IDs (SVIDs); empty requests all variables.
`cancellationToken`	A token that cancels the command if it has not run yet.

Returns

A task that completes with the token of the request once it is sent.

Notes

Throws PdcommException: PdcommStatus.LimitExceeded when ids has more entries than GemHostOptions.MaxPendingIds.

`RequestStatusValuesAsync`

Method

Queues GemHost.RequestStatusValues on the worker thread to send S1F3 for status variable values.

public Task<HsmsToken> RequestStatusValuesAsync(ReadOnlyMemory<uint> ids, CancellationToken cancellationToken = default)

Parameters

Name	Description
`ids`	The status variable IDs (SVIDs); empty requests all variables.
`cancellationToken`	A token that cancels the command if it has not run yet.

Returns

A task that completes with the token of the request once it is sent.

Notes

Throws PdcommException: PdcommStatus.LimitExceeded when ids has more entries than GemHostOptions.MaxPendingIds.

`RespondProgramAsync`

Method

Queues GemHost.RespondProgram on the worker thread.

public Task RespondProgramAsync(GemResult result, GemProgramPutMode mode, byte decision, CancellationToken cancellationToken = default)

result stays valid until the command finishes, even if you dispose it meanwhile. The command reserves SecsLimits.MessageBytes of the GEM item limits of the command byte budget.

Parameters

Name	Description
`result`	The result with outcome `GemOutcome.ProgramReceived`.
`mode`	How a granted or received program is stored when its PPID exists.
`decision`	The application decision; 0 accepts. See the synchronous method for the codes.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes when the reply was sent. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.RespondProgram. It faults with PdcommException (PdcommStatus.ProgramUnconfirmed) when the change was installed but its persistence could not be confirmed.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: result was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store.

`ResyncProgramsAsync`

Method

Queues GemHost.ResyncPrograms on the worker thread.

public Task ResyncProgramsAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes when the parent directory was synchronized. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.ResyncPrograms.

Notes

Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store.

`SendProgramAsync`

Method

Queues GemHost.SendProgram on the worker thread.

public Task<HsmsToken> SendProgramAsync(SecsItem id, SecsItem body, CancellationToken cancellationToken = default)

The encoded PPID and body count against the command byte budget.

Parameters

Name	Description
`id`	The process program ID (PPID): a nonempty ASCII or binary item. It is encoded before the method returns.
`body`	The process program body (PPBODY): an ASCII, binary, `I1` to `I8` or `U1` to `U8` item. It is encoded before the method returns, so the caller may dispose both items afterward.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the token of the S7F3 request. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemHost.SendProgram.

Notes

Throws ArgumentNullException: id or body is null.
Throws ObjectDisposedException: id or body was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store; PdcommStatus.InvalidArgument when the PPID is empty or not an ASCII or binary item, or the body has an unsupported format; PdcommStatus.LimitExceeded when an item exceeds the GEM item limits, the PPID is longer than GemProgramOptions.MaxIdentifierBytes or 120 bytes, or the body payload is longer than GemProgramOptions.MaxBodyBytes or 16,777,215 bytes or, because the request stays pending, when GemProgramOptions.MaxPendingIds is 0 or the PPID is longer than GemProgramOptions.MaxPendingIdentifierBytes.

`StartAsync`

Method

Starts a polling thread that creates and starts a GEM host endpoint.

public static Task<GemHostWorker> StartAsync(string address, HsmsOptions transportOptions, GemHostOptions options, HsmsWorkerOptions workerOptions, CancellationToken cancellationToken = default)

The task faults with ArgumentNullException when address, transportOptions, options or workerOptions is null; with ArgumentOutOfRangeException when workerOptions is invalid or HsmsWorkerOptions.MaxEventBytes cannot hold one frame body (HsmsOptions.MaxFrameBytes minus 14) plus one GEM result reservation (SecsLimits.MessageBytes of the GEM item limits); with OperationCanceledException when cancellationToken is canceled before the worker started; and with any exception of GemHost.Create raised on the worker thread. A startup failure also stops the worker.

Parameters

Name	Description
`address`	The numeric IPv4 or IPv6 socket address, such as `127.0.0.1:5000`; a passive endpoint binds to it (port 0 selects a free port) and an active endpoint connects to it.
`transportOptions`	The HSMS transport options.
`options`	The GEM host options.
`workerOptions`	The command queue, event buffer, polling and shutdown options.
`cancellationToken`	A token that cancels the startup.

Returns

A task that completes with the started worker after the host endpoint was created, configured and started on the worker thread; for a passive endpoint GemWorker.LocalAddress is then available.

`StartWithFormattedProgramsAsync`

Method

Starts a polling thread that creates a GEM host endpoint, enables formatted process program services on it and starts it.

public static Task<GemHostWorker> StartWithFormattedProgramsAsync(string address, HsmsOptions transportOptions, GemHostOptions options, HsmsWorkerOptions workerOptions, GemFormattedProgramConfiguration configuration, CancellationToken cancellationToken = default)

The worker thread applies configuration with GemFormattedProgramConfiguration.Configure; on failure it disposes the host. The task faults with ArgumentNullException when configuration, options, transportOptions or workerOptions is null (a null address is reported by GemHost.Create); with ArgumentOutOfRangeException when workerOptions is invalid or HsmsWorkerOptions.MaxEventBytes cannot hold one frame body plus one GEM result reservation; with OperationCanceledException when cancellationToken is canceled before the worker started; and with any exception of GemHost.Create or GemFormattedProgramConfiguration.Configure raised on the worker thread. A startup failure also stops the worker. Use GemWorker.FormattedPrograms for the formatted program operations.

Parameters

Name	Description
`address`	The numeric IPv4 or IPv6 socket address, such as `127.0.0.1:5000`; a passive endpoint binds to it (port 0 selects a free port) and an active endpoint connects to it.
`transportOptions`	The HSMS transport options.
`options`	The GEM host options.
`workerOptions`	The command queue, event buffer, polling and shutdown options.
`configuration`	The formatted process program services to enable before the transport starts.
`cancellationToken`	A token that cancels the startup.

Returns

A task that completes with the started worker after the host endpoint was created, configured and started on the worker thread; for a passive endpoint GemWorker.LocalAddress is then available.

`StartWithProgramsAsync`

Method

Starts a host worker whose process program store is loaded with initial programs.

public static Task<GemHostWorker> StartWithProgramsAsync(string address, HsmsOptions transportOptions, GemHostOptions options, HsmsWorkerOptions workerOptions, GemProgramConfiguration programs, CancellationToken cancellationToken = default)

The program configuration is validated and copied before this method returns. The task faults with ArgumentNullException when address, transportOptions, options or workerOptions is null; with ArgumentOutOfRangeException when workerOptions is invalid or HsmsWorkerOptions.MaxEventBytes cannot hold one frame body (HsmsOptions.MaxFrameBytes minus 14) plus one GEM result reservation (SecsLimits.MessageBytes of the GEM item limits); with OperationCanceledException when cancellationToken is canceled before the worker started; and with any exception of GemHost.Create raised on the worker thread. A startup failure also stops the worker.

Parameters

Name	Description
`address`	The numeric IPv4 or IPv6 socket address, such as `127.0.0.1:5000`; a passive endpoint binds to it (port 0 selects a free port) and an active endpoint connects to it.
`transportOptions`	The HSMS transport options.
`options`	The GEM host options.
`workerOptions`	The command queue, event buffer, polling and shutdown options.
`programs`	The process program options, the initial programs, and an optional storage path; a `null` path keeps the store in memory.
`cancellationToken`	A token that cancels the startup.

Returns

A task that completes with the started worker after the host endpoint was created, configured and started on the worker thread; for a passive endpoint GemWorker.LocalAddress is then available.

Notes

Throws ArgumentNullException: options, programs or its options are null.
Throws ArgumentException: An initial program is null or the storage path contains a NUL character.
Throws ObjectDisposedException: An initial program item was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidArgument or PdcommStatus.LimitExceeded when the program options or initial programs are invalid or exceed the program limits.

`StartWithProgramsAsync`

Method

Starts a host worker with an empty process program store.

public static Task<GemHostWorker> StartWithProgramsAsync(string address, HsmsOptions transportOptions, GemHostOptions options, HsmsWorkerOptions workerOptions, GemProgramOptions programs, CancellationToken cancellationToken = default)

Process program transactions (stream 7) are handled by the configured store. The task faults with ArgumentNullException when address, transportOptions, options or workerOptions is null; with ArgumentOutOfRangeException when workerOptions is invalid or HsmsWorkerOptions.MaxEventBytes cannot hold one frame body (HsmsOptions.MaxFrameBytes minus 14) plus one GEM result reservation (SecsLimits.MessageBytes of the GEM item limits); with OperationCanceledException when cancellationToken is canceled before the worker started; and with any exception of GemHost.Create raised on the worker thread. A startup failure also stops the worker.

Parameters

Name	Description
`address`	The numeric IPv4 or IPv6 socket address, such as `127.0.0.1:5000`; a passive endpoint binds to it (port 0 selects a free port) and an active endpoint connects to it.
`transportOptions`	The HSMS transport options.
`options`	The GEM host options.
`workerOptions`	The command queue, event buffer, polling and shutdown options.
`programs`	The process program limits and grant policy; the store is kept in memory.
`cancellationToken`	A token that cancels the startup.

Returns

A task that completes with the started worker after the host endpoint was created, configured and started on the worker thread; for a passive endpoint GemWorker.LocalAddress is then available.

Notes

Throws ArgumentNullException: programs is null.
Throws PdcommException: PdcommStatus.InvalidArgument when the grant policy of programs is undefined.

`StartWithSpoolingAsync`

Method

Starts a host worker whose endpoint can send spooling requests.

public static Task<GemHostWorker> StartWithSpoolingAsync(string address, HsmsOptions transportOptions, GemHostOptions options, HsmsWorkerOptions workerOptions, GemSpoolHostOptions spooling, CancellationToken cancellationToken = default)

The task faults as for GemHostWorker.StartAsync and also with any exception of GemHost.ConfigureSpoolHost raised on the worker thread. Only a worker started this way accepts the spooling commands.

Parameters

Name	Description
`address`	The numeric IPv4 or IPv6 socket address, such as `127.0.0.1:5000`; a passive endpoint binds to it (port 0 selects a free port) and an active endpoint connects to it.
`transportOptions`	The HSMS transport options.
`options`	The GEM host options.
`workerOptions`	The command queue, event buffer, polling and shutdown options.
`spooling`	The limits of the spooling requests; they are copied before this method returns.
`cancellationToken`	A token that cancels the startup.

Returns

A task that completes with the started worker after the host endpoint was created, configured and started on the worker thread; for a passive endpoint GemWorker.LocalAddress is then available.

Notes

Throws ArgumentNullException: spooling is null.
Throws OperationCanceledException: cancellationToken is already canceled.