PDComm.GemWorker

클래스

GemHostWorker와 GemEquipmentWorker가 공유하는 멤버를 제공합니다. 전용 폴링 스레드가 소유하는 GEM 끝점입니다.

public abstract class GemWorker : IAsyncDisposable

작업자 스레드가 끝점을 만들고 시작하며 소유합니다. 이 스레드는 전송을 폴링하고, 모든 전송 이벤트를 GemEndpoint.HandleEvent에 전달하며, 그 결과로 생긴 GemEvent 객체를 GemWorker.ReadEventsAsync용으로 버퍼링합니다. 새 작업이 도착하지 않으면 폴링 사이에 최대 HsmsWorkerOptions.PollIntervalMilliseconds 동안 기다립니다.

각 *Async 명령은 큐에 들어가 제출 순서대로 작업자 스레드에서 실행됩니다. 큐는 최대 HsmsWorkerOptions.CommandCapacity개의 명령과 HsmsWorkerOptions.MaxCommandBytes의 명령 입력을 받습니다. 어느 한도든 넘는 명령은 큐에 들어가지 않으며 그 작업은 PdcommException(PdcommStatus.Backpressure)으로 실패합니다. 입력 버퍼는 명령 메서드가 반환되기 전에 복사됩니다.

이벤트 버퍼는 최대 HsmsWorkerOptions.EventCapacity개의 이벤트와 HsmsWorkerOptions.MaxEventBytes를 보관합니다. 각 이벤트는 원시 본문 길이에 결과용 GEM 아이템 한도 SecsLimits.MessageBytes를 더한 크기를 예약합니다. 버퍼가 가득 찬 동안에는 작업자가 전송 읽기와 폴링을 멈추고, 메시지를 보내는 명령은 PdcommStatus.Backpressure로 실패하므로 이벤트를 계속 읽어야 합니다.

작업자는 GemWorker.StopAsync로 중지하고 GemWorker.Completion을 기다린 다음, 보통 await using을 통해 GemWorker.DisposeAsync로 해제합니다.

멤버

`BeginCommunicationAsync`

메서드

S1F13을 보내도록 작업자 스레드에서 실행할 GemEndpoint.BeginCommunication을 큐에 넣습니다.

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

명령은 끝점을 소유한 작업자 스레드에서 실행됩니다. 명령 큐나 바이트 예산이 가득 찼거나, 이벤트 버퍼가 가득 차서 이벤트 출력이 막힌 동안 명령이 실행되면 PdcommException(PdcommStatus.Backpressure)으로, 작업자가 명령 수락을 멈춘 뒤에는 ObjectDisposedException으로 작업이 실패하며, 명령이 실행되기 전에 cancellationToken이 취소되면 작업이 취소됩니다. 그 밖에는 GemEndpoint.BeginCommunication의 예외를 전달합니다.

매개변수

이름	설명
`cancellationToken`	아직 실행되지 않은 명령을 취소하는 토큰입니다.

반환값

요청을 보내면 S1F13 요청의 토큰으로 완료되는 작업입니다. S1F14 응답은 GemEvent로 도착합니다.

`CancelAsync`

메서드

작업자 스레드에서 실행하도록 GemEndpoint.Cancel을 큐에 넣습니다.

public Task<bool> CancelAsync(HsmsToken token, CancellationToken cancellationToken = default)

명령은 끝점을 소유한 작업자 스레드에서 실행됩니다. 명령 큐나 바이트 예산이 가득 차면 PdcommException(PdcommStatus.Backpressure)으로, 작업자가 명령 수락을 멈춘 뒤에는 ObjectDisposedException으로 작업이 실패하며, 명령이 실행되기 전에 cancellationToken이 취소되면 작업이 취소됩니다. 그 밖에는 GemEndpoint.Cancel의 예외를 전달합니다.

매개변수

이름	설명
`token`	요청을 제출할 때 반환된 토큰입니다.
`cancellationToken`	아직 실행되지 않은 명령을 취소하는 토큰입니다.

반환값

거래가 대기 중이었고 이제 취소되었으면 true로 완료되는 작업입니다.

`DeselectAsync`

메서드

HSMS Deselect.req 제어 메시지를 보내도록 작업자 스레드에서 실행할 GemEndpoint.Deselect를 큐에 넣습니다.

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

매개변수

이름	설명
`cancellationToken`	아직 실행되지 않은 명령을 취소하는 토큰입니다.

반환값

제어 거래의 토큰으로 완료되는 작업입니다.

`DisposeAsync`

메서드

작업자를 중지하고, 끝점을 해제하고, 작업자 스레드가 종료될 때까지 기다립니다.

public ValueTask DisposeAsync()

작업자는 명령 수락을 멈추며, 아직 실행되지 않은 큐의 명령은 ObjectDisposedException으로 실패합니다. 버퍼에 있는 이벤트와 종료 중에 읽은 이벤트는 전달되지 않고 해제됩니다. 이미 전달된 이벤트는 계속 유효하며 읽는 쪽이 소유합니다. 작업자는 전송을 중지하고 닫힐 때까지 최대 HsmsWorkerOptions.ShutdownTimeoutMilliseconds 동안 기다립니다. 작업자가 실패로 끝났으면(예: 종료 기한의 TimeoutException 또는 이전의 치명적 오류) 반환된 작업이 스레드가 종료된 뒤 그 예외를 다시 throw합니다.

반환값

작업자 스레드가 종료되고 버퍼의 이벤트가 버려진 뒤 완료되는 작업입니다.

`GetLocalAddressAsync`

메서드

작업자 스레드에서 실행하도록 GemEndpoint.GetLocalAddress를 큐에 넣습니다.

public Task<string> GetLocalAddressAsync(CancellationToken cancellationToken = default)

매개변수

이름	설명
`cancellationToken`	아직 실행되지 않은 명령을 취소하는 토큰입니다.

반환값

숫자 로컬 소켓 주소로 완료되는 작업입니다.

`GetStateAsync`

메서드

작업자 스레드에서 실행하도록 GemEndpoint.GetState를 큐에 넣습니다.

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

매개변수

이름	설명
`cancellationToken`	아직 실행되지 않은 명령을 취소하는 토큰입니다.

반환값

GEM 상태의 스냅샷으로 완료되는 작업입니다.

`GetTransportStateAsync`

메서드

작업자 스레드에서 실행하도록 GemEndpoint.GetTransportState를 큐에 넣습니다.

public Task<HsmsState> GetTransportStateAsync(CancellationToken cancellationToken = default)

매개변수

이름	설명
`cancellationToken`	아직 실행되지 않은 명령을 취소하는 토큰입니다.

반환값

HSMS 연결 상태로 완료되는 작업입니다.

`IsPendingAsync`

메서드

작업자 스레드에서 실행하도록 GemEndpoint.IsPending을 큐에 넣습니다.

public Task<bool> IsPendingAsync(HsmsToken token, CancellationToken cancellationToken = default)

매개변수

이름	설명
`token`	요청을 제출할 때 반환된 토큰입니다.
`cancellationToken`	아직 실행되지 않은 명령을 취소하는 토큰입니다.

반환값

거래가 아직 대기 중이면 true로 완료되는 작업입니다.

`LinktestAsync`

메서드

HSMS Linktest.req 제어 메시지를 보내도록 작업자 스레드에서 실행할 GemEndpoint.Linktest를 큐에 넣습니다.

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

매개변수

이름	설명
`cancellationToken`	아직 실행되지 않은 명령을 취소하는 토큰입니다.

반환값

제어 거래의 토큰으로 완료되는 작업입니다.

`ReadEventsAsync`

메서드

작업자 스레드가 만든 GEM 이벤트를 순서대로 읽습니다.

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

이벤트를 읽으면 이벤트 버퍼의 공간이 비워집니다. 여러 열거를 동시에 실행할 수 있으며, 각 이벤트는 그중 하나에만 전달됩니다. 시퀀스는 작업자 스레드가 종료되고 버퍼의 모든 이벤트를 읽은 뒤 끝납니다. 작업자가 실패했으면 그때 열거가 GemWorker.Completion이 보고한 예외를 throw합니다. GemWorker.DisposeAsync가 실행될 때 버퍼에 남아 있는 이벤트는 전달되지 않고 해제됩니다.

매개변수

이름	설명
`cancellationToken`	열거를 끝내는 토큰입니다.

반환값

이벤트의 비동기 시퀀스입니다. 호출자가 각 GemEvent를 소유하며 해제해야 합니다.

참고

OperationCanceledException 예외: 열거 중에 cancellationToken이 취소되었습니다.

`ReplyRawAsync`

메서드

원시 SECS-II 응답을 보내도록 작업자 스레드에서 실행할 GemEndpoint.ReplyRaw를 큐에 넣습니다.

public Task ReplyRawAsync(HsmsEvent primary, byte stream, byte function, bool replyExpected, ReadOnlyMemory<byte> body, CancellationToken cancellationToken = default)

작업자는 명령이 완료될 때까지 primary를 유지하므로, 호출자는 이 메서드가 반환된 뒤 해제해도 됩니다. 본문은 메서드가 반환되기 전에 복사되며, 1차 메시지와 응답 본문의 길이는 명령 바이트 예산에 포함됩니다. 명령은 끝점을 소유한 작업자 스레드에서 실행됩니다. 명령 큐나 바이트 예산이 가득 찼거나, 이벤트 버퍼가 가득 차서 이벤트 출력이 막힌 동안 명령이 실행되면 PdcommException(PdcommStatus.Backpressure)으로, 작업자가 명령 수락을 멈춘 뒤에는 ObjectDisposedException으로 작업이 실패하며, 명령이 실행되기 전에 cancellationToken이 취소되면 작업이 취소됩니다. 그 밖에는 GemEndpoint.ReplyRaw의 예외를 전달합니다.

매개변수

이름	설명
`primary`	응답할 수신 1차 메시지 이벤트입니다. 보통 `GemResultKind.Unhandled` 결과의 `GemEvent.TransportEvent`입니다.
`stream`	응답의 SECS-II 스트림 번호입니다.
`function`	응답의 SECS-II 펑션 번호이거나, 거래를 중단하려면 0입니다.
`replyExpected`	응답에 응답 요청(W) 비트를 설정할지 여부입니다. 응답에는 보통 설정하지 않습니다.
`body`	인코딩된 완전한 SECS-II 아이템 하나이거나, 헤더만 있는 응답이면 비워 둡니다.
`cancellationToken`	아직 실행되지 않은 명령을 취소하는 토큰입니다.

반환값

전송이 응답을 수락하면 완료되는 작업입니다.

참고

ArgumentNullException 예외: primary가 null입니다.
ObjectDisposedException 예외: primary가 해제되었습니다.
OperationCanceledException 예외: cancellationToken이 이미 취소되었습니다.
PdcommException 예외: body가 HsmsOptions.MaxFrameBytes에서 프레임 오버헤드 14바이트를 뺀 값보다 길거나, 비어 있지 않은 본문이 전송의 SecsLimits.MessageBytes보다 길면 PdcommStatus.LimitExceeded입니다.

`RequestRawAsync`

메서드

원시 SECS-II 1차 메시지를 보내도록 작업자 스레드에서 실행할 GemEndpoint.RequestRaw를 큐에 넣습니다.

public Task<HsmsToken> RequestRawAsync(byte stream, byte function, bool replyExpected, ReadOnlyMemory<byte> body, CancellationToken cancellationToken = default)

본문은 메서드가 반환되기 전에 복사되며 명령 바이트 예산에 포함됩니다. 명령은 끝점을 소유한 작업자 스레드에서 실행됩니다. 명령 큐나 바이트 예산이 가득 찼거나, 이벤트 버퍼가 가득 차서 이벤트 출력이 막힌 동안 명령이 실행되면 PdcommException(PdcommStatus.Backpressure)으로, 작업자가 명령 수락을 멈춘 뒤에는 ObjectDisposedException으로 작업이 실패하며, 명령이 실행되기 전에 cancellationToken이 취소되면 작업이 취소됩니다. 그 밖에는 GemEndpoint.RequestRaw의 예외를 전달합니다.

매개변수

이름	설명
`stream`	SECS-II 스트림 번호입니다.
`function`	SECS-II 펑션 번호입니다. 1차 메시지는 홀수를 사용합니다.
`replyExpected`	메시지에 응답 요청(W) 비트를 설정할지 여부입니다.
`body`	인코딩된 완전한 SECS-II 아이템 하나이거나, 헤더만 있는 메시지이면 비워 둡니다.
`cancellationToken`	아직 실행되지 않은 명령을 취소하는 토큰입니다.

반환값

전송이 요청을 수락하면 그 요청의 토큰으로 완료되는 작업입니다.

참고

PdcommException 예외: body가 HsmsOptions.MaxFrameBytes에서 프레임 오버헤드 14바이트를 뺀 값보다 길거나, 비어 있지 않은 본문이 전송의 SecsLimits.MessageBytes보다 길면 PdcommStatus.LimitExceeded입니다.

`SelectAsync`

메서드

HSMS Select.req 제어 메시지를 보내도록 작업자 스레드에서 실행할 GemEndpoint.Select를 큐에 넣습니다.

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

매개변수

이름	설명
`cancellationToken`	아직 실행되지 않은 명령을 취소하는 토큰입니다.

반환값

제어 거래의 토큰으로 완료되는 작업입니다.

`StopAsync`

메서드

작업자 스레드에서 전송을 정상 중지하는 명령을 큐에 넣습니다.

public Task StopAsync(CancellationToken cancellationToken = default)

앞서 큐에 넣은 명령이 먼저 실행됩니다. 중지가 시작된 뒤에도 작업자는 전송이 닫히고, 모든 네이티브 이벤트를 읽었고, 버퍼 공간을 기다리는 이벤트가 없고, 대기 중인 명령이 없을 때까지 명령을 실행하고 이벤트를 전달한 다음 스레드를 종료합니다. 비우기가 끝날 수 있도록 GemWorker.ReadEventsAsync로 이벤트를 계속 읽어야 합니다. HsmsWorkerOptions.ShutdownTimeoutMilliseconds 안에 끝나지 않으면 GemWorker.Completion이 TimeoutException으로 실패합니다.

명령 큐가 가득 차면 PdcommException(PdcommStatus.Backpressure)으로, 작업자가 명령 수락을 멈춘 뒤에는 ObjectDisposedException으로 작업이 실패하며, 명령이 실행되기 전에 cancellationToken이 취소되면 작업이 취소됩니다.

매개변수

이름	설명
`cancellationToken`	아직 실행되지 않은 명령을 취소하는 토큰입니다.

반환값

작업자가 끝났을 때가 아니라 작업자 스레드가 전송 닫기를 시작했을 때 완료되는 작업입니다. 작업자가 끝나기를 기다리려면 GemWorker.Completion을 기다립니다.

`Completion`

속성

작업자 스레드가 종료되면 완료되는 작업을 가져옵니다.

public Task Completion { get; }

정상 중지 또는 제시간에 끝난 해제 후에는 작업이 성공적으로 완료됩니다. 작업자를 종료시킨 예외로 작업이 실패할 수 있습니다. 중지가 시작된 뒤 HsmsWorkerOptions.ShutdownTimeoutMilliseconds 안에 전송이 닫히고 비워지지 않으면 TimeoutException, 끝점에서 예외가 발생했으면 그 예외(예: PdcommStatus.Poisoned인 PdcommException)입니다.

`FormattedPrograms`

속성

이 작업자의 비동기 정형 프로세스 프로그램 작업을 가져옵니다.

public GemFormattedProgramsWorker FormattedPrograms { get; }

접근할 때마다 해제할 필요가 없는 새 경량 객체를 만듭니다. 이 객체의 메서드는 해당 GemFormattedPrograms 메서드를 작업자의 폴링 스레드에서 실행합니다. 로드된 네이티브 라이브러리에 정형 프로세스 프로그램 내보내기가 없으면 큐에 넣은 각 명령이 NotSupportedException으로 실패합니다. 서비스는 시작할 때 GemHostWorker.StartWithFormattedProgramsAsync 또는 GemEquipmentWorker.StartWithFormattedProgramsAsync로 활성화합니다.

반환값

이 작업자에 명령을 큐에 넣는 새 GemFormattedProgramsWorker입니다.

`LocalAddress`

속성

전송이 수신 대기 중이거나 연결된 동안 숫자 로컬 소켓 주소를 가져오고, 그 밖에는 null을 가져옵니다.

public string? LocalAddress { get; }

패시브 끝점이면 시작 작업이 완료될 때 주소를 사용할 수 있습니다.