PDComm.Secs1Worker

Class

Runs a SECS-I (SEMI E4) serial line protocol endpoint on a dedicated background thread.

public sealed class Secs1Worker : IAsyncDisposable

The application owns the serial port: it passes Secs1Read and Secs1Write callbacks, and the worker never opens or closes a port. The worker thread creates, polls and destroys the native endpoint and calls the callbacks; the endpoint's timers run on a millisecond clock, so every *Ticks value of Secs1Options is in milliseconds.

Submit messages with Secs1Worker.SubmitAsync (one outbound message is sent at a time) and read results and received messages with Secs1Worker.ReadEventsAsync. The worker polls the line only while the event buffer has room for one more maximum-size message, so read events continuously.

Unlike HsmsWorker, the command methods throw queue and state errors synchronously. Calling any method from inside a callback throws InvalidOperationException.

Members

DisposeAsync

Method

Stops the worker thread, which stops and destroys the native endpoint.

public ValueTask DisposeAsync()

Queued commands fail with ObjectDisposedException. The returned task faults with TimeoutException if the thread does not exit within Secs1WorkerOptions.ShutdownTimeoutMilliseconds, and with the worker's terminal error if it failed.

Returns

A task that completes when the worker thread has exited.

Notes

• Throws InvalidOperationException: The method was called from a read or write callback.

GetStateAsync

Method

Reads the endpoint's lifecycle flags on the worker thread.

public Task<Secs1State> GetStateAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
cancellationToken	A token that cancels the command if it has not started running.

Returns

A task whose result is a snapshot of the endpoint state.

Notes

• Throws InvalidOperationException: The method was called from a read or write callback.
• Throws OperationCanceledException: cancellationToken is already canceled.
• Throws ObjectDisposedException: The worker is stopping or has exited.
• Throws PdcommException: The command queue or Secs1WorkerOptions.MaxCommandBytes is full (PdcommStatus.Backpressure).

ReadEventsAsync

Method

Reads the events produced by the endpoint, in order.

public IAsyncEnumerable<Secs1Event> ReadEventsAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
cancellationToken	A token that ends the enumeration with OperationCanceledException.

Returns

An asynchronous sequence of events. Bodies are managed copies, so events need no disposal. The sequence ends when the worker exits, and throws the worker's terminal error if it failed.

ResetAsync

Method

Clears a line fault so the endpoint can resume.

public Task ResetAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
cancellationToken	A token that cancels the command if it has not started running.

Returns

A task that completes when the fault is cleared. Partial transfers are discarded. The task faults with PdcommException: PdcommStatus.InvalidState when the endpoint is stopped, and PdcommStatus.Backpressure when the line is not faulted.

Notes

• Throws InvalidOperationException: The method was called from a read or write callback.
• Throws OperationCanceledException: cancellationToken is already canceled.
• Throws ObjectDisposedException: The worker is stopping or has exited.
• Throws PdcommException: The command queue or Secs1WorkerOptions.MaxCommandBytes is full (PdcommStatus.Backpressure).

RestartAsync

Method

Starts a stopped endpoint again with a new generation.

public Task RestartAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
cancellationToken	A token that cancels the command if it has not started running.

Returns

A task that completes when the endpoint has started. Tokens of the previous generation no longer match. The task faults with PdcommException (PdcommStatus.InvalidState) if the endpoint is running.

Notes

• Throws InvalidOperationException: The method was called from a read or write callback.
• Throws OperationCanceledException: cancellationToken is already canceled.
• Throws ObjectDisposedException: The worker is stopping or has exited.
• Throws PdcommException: The command queue or Secs1WorkerOptions.MaxCommandBytes is full (PdcommStatus.Backpressure).

StartAsync

Method

Creates a SECS-I endpoint on a new worker thread and starts it.

public static Task<Secs1Worker> StartAsync(Secs1Options options, Secs1WorkerOptions policy, Secs1Read read, Secs1Write write, CancellationToken cancellationToken = default)

Parameters

Name	Description
options	The line timing, retry and capacity options.
policy	The worker's queue capacities and timing.
read	The callback that reads bytes from the serial line.
write	The callback that writes bytes to the serial line.
cancellationToken	A token checked once before the worker thread starts; it does not cancel a startup in progress.

Returns

A task whose result is the running worker, which the caller owns and must dispose. The task faults with PdcommException if the native endpoint cannot be created or started, for example PdcommStatus.InvalidArgument for invalid options.

Notes

• Throws ArgumentNullException: An argument is null.
• Throws OperationCanceledException: cancellationToken is already canceled.
• Throws NotSupportedException: The loaded native library does not export the SECS-I API.
• Throws ArgumentOutOfRangeException: policy has a nonpositive capacity or interval or a negative byte budget, Secs1Options.MaxBodyBytes or Secs1Options.MaxIoChunk exceeds Int32.MaxValue, or Secs1WorkerOptions.MaxEventBytes is smaller than Secs1Options.MaxBodyBytes.

StopAsync

Method

Stops the endpoint and discards its runtime state, without invoking the callbacks.

public Task StopAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
cancellationToken	A token that cancels the command if it has not started running.

Returns

A task that completes when the endpoint has stopped. The worker thread keeps running; call Secs1Worker.RestartAsync to start a new generation or Secs1Worker.DisposeAsync to exit. The task faults with PdcommException (PdcommStatus.InvalidState) if the endpoint is already stopped.

Notes

• Throws InvalidOperationException: The method was called from a read or write callback.
• Throws OperationCanceledException: cancellationToken is already canceled.
• Throws ObjectDisposedException: The worker is stopping or has exited.
• Throws PdcommException: The command queue or Secs1WorkerOptions.MaxCommandBytes is full (PdcommStatus.Backpressure).

SubmitAsync

Method

Queues a message for transmission on the serial line.

public Task<Secs1Token> SubmitAsync(Secs1Message message, CancellationToken cancellationToken = default)

Parameters

Name	Description
message	The message to send; its body is copied.
cancellationToken	A token that cancels the command if it has not started running.

Returns

A task whose result is the message's token once the endpoint accepted it. The outcome arrives later as an Secs1EventKind.OutboundComplete or Secs1EventKind.OutboundFailed event with that token. The task faults with PdcommException: PdcommStatus.Backpressure while another message is still being sent, PdcommStatus.InvalidState when the endpoint is stopped or faulted, PdcommStatus.InvalidArgument for an invalid header, and PdcommStatus.LimitExceeded for a message beyond Secs1Options.MaxOutboundBodyBytes or Secs1Options.MaxOutboundBlocks.

Notes

• Throws ArgumentNullException: message is null.
• Throws InvalidOperationException: The method was called from a read or write callback.
• Throws OperationCanceledException: cancellationToken is already canceled.
• Throws ObjectDisposedException: The worker is stopping or has exited.
• Throws PdcommException: The body is larger than Secs1Options.MaxBodyBytes (PdcommStatus.LimitExceeded), or the command queue or Secs1WorkerOptions.MaxCommandBytes is full (PdcommStatus.Backpressure).

CallbackException

Property

Gets the most recent exception thrown by a read or write callback, or null if none was thrown.

public Exception? CallbackException { get; }

A callback that throws, or that reports more bytes than its buffer holds, is reported to the endpoint as Secs1IoStatus.Other, which faults the line.

Completion

Property

Gets a task that completes when the worker thread has exited, or faults with the error that ended it.

public Task Completion { get; }