構文
enum class PartySendMessageOptions : int32_t
{
Default = 0x0000,
GuaranteedDelivery = 0x0001,
BestEffortDelivery = 0x0000,
SequentialDelivery = 0x0002,
NonsequentialDelivery = 0x0000,
CopyDataBuffers = 0x0000,
DontCopyDataBuffers = 0x0004,
CoalesceOpportunistically = 0x0000,
AlwaysCoalesceUntilFlushed = 0x0008,
RequireTimelyAcknowledgement = 0x0000,
AllowLazyAcknowledgement = 0x0010,
}
定数
| 定数 | 説明 |
|---|---|
| Default | 既定の PartySendMessageOptions を使用します。 既定のオプションは BestEffortDelivery、NonsequentialDelivery、CopyDataBuffers、CoalesceOpportunistically、および RequireTimelyAcknowledgement です。 |
| GuaranteedDelivery | 必要に応じて再送信することで、メッセージがすべてのターゲットに配信されることを保証します。 このオプション フラグは、ターゲット エンドポイントが破棄されない限り、環境的なパケット損失に関係なく、メッセージが各ターゲット エンドポイントに到着することを保証します。パケット送信は必要に応じて再試行されます。 このオプション フラグは、常に宛先に到達しなければならない、または到達しない場合はターゲットをネットワークから削除する必要がある重要な状態情報を送信する場合に適しています。冗長性がない、または失われた場合に補間/外挿できない機能がないメッセージ コンテンツで、パケット再送信が必要になった場合の帯域幅使用量の増加に値するものと共に使用してください。 配信を保証しても、それ自体で特定の配信順序を保証するわけではありません。順序を強制するには SequentialDelivery オプション フラグを使用してください。 |
| BestEffortDelivery | メッセージをベスト エフォートで送信し、パケット損失を無視します。 このオプション フラグは、メッセージを送信する試行を 1 回だけ要求します。環境的なパケット損失が発生した場合、送信は再試行されず、アプリケーションはメッセージの欠落を処理する準備をしておく必要があります。 このオプション フラグは、常に更新され、すべての更新が到着する必要のない情報に適しています。既に冗長性があるか、失われた場合に補間/外挿できる機能があるメッセージ コンテンツで、再送信のための追加の帯域幅の価値がないものと共に使用してください。 これは、GuaranteedDelivery オプション フラグが指定されていない場合の既定です。 |
| SequentialDelivery | このローカル エンドポイントからターゲット エンドポイントに送信された、シーケンシャルに送信された他のメッセージとの相対的な順序でメッセージを配信します。 SequentialDelivery は、異なるローカル エンドポイントから送信されるメッセージまたは異なるターゲット エンドポイントに送信されるメッセージの順序については保証しません。各エンドポイント ペアリングは別のシーケンス空間として扱われます。 シーケンシャル メッセージと非シーケンシャル メッセージとの間の順序については保証されません。 このオプション フラグは、少しネットワーク効率が下がり、パケット損失や環境による並べ替えがある場合に受信するのに少し長く待つ可能性があっても、特定のシーケンスで宛先に到達する必要がある状態情報に適しています。 SequentialDelivery を GuaranteedDelivery と共に使用すると、以前に送信されたシーケンシャル メッセージが到着するのを待っている間、メッセージがターゲット エンドポイントでキューに入れられる場合があります。これにより、環境的なパケット損失や並べ替えが発生した場合に感知されるレイテンシーが増加する場合がありますが、ターゲット エンドポイントは常にすべてのメッセージを送信された順序で受信します。 SequentialDelivery を BestEffortDelivery と共に使用すると、あるメッセージがターゲット エンドポイントに順不同で到着し、後のシーケンシャル メッセージが既に配信されていた場合、メッセージが破棄される可能性があります。ターゲット エンドポイントは常にシーケンスが前進するのを見ますが、そのシーケンスにギャップがある可能性があります。古いメッセージが新しいメッセージの後に配信されることはありません。 |
| NonsequentialDelivery | メッセージが到着次第、ターゲットに配信します。 非シーケンシャル配信オプションで送信されたメッセージは、シーケンシャルまたは非シーケンシャルの他のメッセージとの相対的な配信順序について保証しません。メッセージは到着次第ターゲットに配信されますが、パケット損失や環境による並べ替えがある場合、送信された順序と同じでない可能性があります。 このオプション フラグは、任意の順序で処理するのが安全か、既に固有の順序情報を持っており、最大のネットワーク効率と最小の感知レイテンシーを望むメッセージに適しています。 これは、SequentialDelivery オプション フラグが指定されていない場合の既定です。 |
| CopyDataBuffers | Party ライブラリに、提供されたデータ バッファーのコピーを作成して後続の送信に使用するよう指示します。 提供された PartyDataBuffer 構造体内のメモリの内容がコピーされるため、呼び出し元は PartyLocalEndpoint::SendMessage() が戻った後にバッファーを保持する必要がありません。これは、DontCopyDataBuffers オプション フラグを使用するよりも便利ですが、わずかに効率が低下します。 これは、DontCopyDataBuffers オプション フラグが指定されていない場合の既定です。 |
| DontCopyDataBuffers | Party ライブラリに、提供されたデータ バッファーを直接使用するよう通知し、呼び出し元がライブラリがそれらを必要としなくなるまでメモリを有効に保つことを通知します。 提供された PartyDataBuffer 構造体が参照するメモリはコピーされず、代わりに一時的に所有権が Party ライブラリに移され、送信プロセス中に追加のコピー オーバーヘッドなしで直接メモリにアクセスできます。ライブラリがそれらを必要としなくなり、PartyDataBuffersReturnedStateChange を介して所有権が戻されるまで、メモリ バッファーが有効かつ変更されないままであることを保証するのは、呼び出し元の責任です。これは CopyDataBuffers オプションを使用するよりも効率的ですが、便利さは劣る場合があります。 PartyDataBuffer 構造体自体は、PartyLocalEndpoint::SendMessage() 呼び出しが戻った後は有効なままである必要はなく、それらが参照するメモリのみが有効なままである必要があります。 |
| CoalesceOpportunistically | このメッセージが他のキューされたメッセージと結合される必要があるが、待機中のメッセージがない場合は送信を遅延させないよう指定します。 複数のメッセージを 1 つのパケットに結合すると、結合するために送信を遅延させると特定のメッセージの感知レイテンシーが増加する可能性を犠牲にして、帯域幅効率を最大化 (パケットごとのオーバーヘッドを削減) できます。このフラグ付きで送信すると、Party ライブラリは他のキューされたメッセージが利用可能な場合はメッセージを結合しますが、存在しない場合はメッセージが即座に送信できる場合は追加のメッセージを待ちません。 ネットワーク更新を通常、他のメッセージと同時にキューされる可能性が低く、遅延しても帯域幅効率が向上しない、単一の定期的なメッセージにバッチ処理する場合は、このフラグを使用してください。 このフラグはメッセージがすぐに送信を開始することを保証しません。接続品質または受信側の応答性が現在追加データの送信をサポートしていないと見られる場合、メッセージは次の送信機会を待つためにキューに入れられる可能性があります。 これは、AlwaysCoalesceUntilFlushed オプション フラグが指定されていない場合の既定です。 |
| AlwaysCoalesceUntilFlushed | このメッセージは常に他のメッセージと結合しようとし、送信を開始するために PartyLocalEndpoint::FlushMessages() 呼び出しを期待するように指定します。 複数のメッセージを 1 つのパケットに結合すると、結合するために送信を遅延させると特定のメッセージの感知レイテンシーが増加する可能性を犠牲にして、帯域幅効率を最大化 (パケットごとのオーバーヘッドを削減) できます。このフラグ付きで送信すると、Party ライブラリは常にメッセージの結合を優先し、PartyLocalEndpoint::FlushMessages() が呼び出されるまで送信を遅延させます。 通常、同じ更新ループで同じターゲットに多くの小さなメッセージを送信し、Party ライブラリに完全な更新ループの反復が完了したことを明示的に通知したい場合は、このフラグの使用を検討してください。 このフラグを付けても、明示的な PartyLocalEndpoint::FlushMessages() 呼び出しを必要とせずにメッセージが送信を開始するシナリオがあります。これは、他の理由で既に送信されている他のキューされたメッセージがあり、パケット内にこのメッセージを含めるスペースがある場合に発生します。同様に、完全なパケットを送信するのに十分なメッセージ データ バイトが存在し、それ以上の結合が不可能な場合、パケットは送信されます。すべてのメッセージが既に送信を開始している場合の PartyLocalEndpoint::FlushMessages() の呼び出しは無害です。 |
| RequireTimelyAcknowledgement | このメッセージがタイムリーに (必要に応じて) 確認応答されるべきであることを示します。 受信者はメッセージの受信を確認応答して、送信者に配信の成功または失敗を通知することで、GuaranteedDelivery オプション フラグ付きで送信されたメッセージを含むドロップされたパケットを再試行するといったことができるようにします。確認応答は通常、双方向の通信の一環としてパケットに便乗しますが、戻り方向にパケットが流れていない場合、このフラグはターゲット エンドポイントに、便乗の機会について小さな内部管理タイムアウトのみを待機し、その後、送信者に通知するための確認応答パケットを強制するよう指示します。その専用パケットは追加のオーバーヘッドを消費しますが、送信者が必要な再試行を発行するためのタイムリーな状態を確実に取得できるようにします。 ほとんどの保証配信メッセージにこのフラグを使用することをお勧めします。レイテンシーに敏感なメッセージとうまく機能します。また、双方向の保証配信送信パターンが頻繁でない、または予測できない場合にもうまく機能します。 これは、AllowLazyAcknowledgement オプション フラグが指定されていない場合の既定です。 GuaranteedDelivery オプション フラグが指定されていない場合、このフラグは無視されます。 |
| AllowLazyAcknowledgement | このメッセージが緊急にではなく、都合の良いときに確認応答できることを示します。 受信者はメッセージの受信を確認応答して、送信者に配信の成功または失敗を通知することで、GuaranteedDelivery オプション フラグ付きで送信されたメッセージを含むドロップされたパケットを再試行するといったことができるようにします。確認応答は通常、双方向の通信の一環としてパケットに便乗しますが、戻り方向にパケットが流れていない場合、このフラグはターゲット エンドポイントに、送信者に通知するための確認応答パケットを強制せずに便乗の機会を待つよう指示します。これにより、送信者が必要な再試行の状態を知るのが遅れますが、専用パケットによって消費される追加のオーバーヘッドを回避します。 “ファイア アンド フォーゲット” でレイテンシーに敏感でない保証配信メッセージにこのフラグの使用を検討してください。双方向の送信パターンが頻繁な場合、オーバーヘッドを削減することもあります。 GuaranteedDelivery オプション フラグも指定されていない場合、このフラグは無視されます。 |
要件
ヘッダー: Party.h関連項目
Party メンバーPartySendMessageQueuingConfiguration
PartyDataBuffersReturnedStateChange
PartyLocalEndpoint::SendMessage
PartyLocalEndpoint::FlushMessages