Syntax
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,
}
Constants
| Constant | Description |
|---|---|
| Default | 使用默认 PartySendMessageOptions。 默认选项为 BestEffortDelivery、NonsequentialDelivery、CopyDataBuffers、CoalesceOpportunistically 和 RequireTimelyAcknowledgement。 |
| GuaranteedDelivery | 确保消息传递到所有目标，必要时重新传输。 此选项标志保证消息将到达每个目标终结点，而不管环境数据包丢失如何，除非目标终结点被销毁。数据包传输将根据需要重试。 此选项标志非常适合发送必须始终到达目的地的重要状态信息，否则应将目标从网络中移除。将其用于以下消息内容：这些消息内容不具备冗余或在丢失时无法进行插值/外推的能力，并且当需要数据包重传时值得增加潜在的带宽使用。 保证传递本身并不意味着保证特定的传递顺序；请使用 SequentialDelivery 选项标志强制执行排序。 |
| BestEffortDelivery | 尽力传输消息并忽略任何数据包丢失。 此选项标志仅请求一次尝试传输消息。如果发生环境数据包丢失，传输将不会重试，应用程序应准备好处理消息缺失的情况。 此选项标志非常适合正在不断更新且不需要每次更新都到达的信息。将其用于以下消息内容：这些消息内容已经具备冗余或在丢失时能够进行插值/外推的能力，并且不值得使用额外的带宽进行重传。 如果未指定 GuaranteedDelivery 选项标志，则此为默认值。 |
| SequentialDelivery | 按相对于同样按顺序发送的、从此本地终结点发送到目标终结点的其他消息的顺序，来传递该消息。 SequentialDelivery 不提供任何有关从不同本地终结点发送和/或发送到不同目标终结点的消息的顺序的保证。每个终结点配对应视为单独的顺序空间。 不保证顺序消息相对于非顺序消息的顺序。 此选项标志非常适合应以特定顺序到达目的地的状态信息，即使这意味着略降低网络效率，并且在环境中出现数据包丢失或重新排序时可能需要等待更长时间才能收到。 将 SequentialDelivery 与 GuaranteedDelivery 一起使用可能会导致消息在目标终结点上排队，同时等待先前发送的顺序消息到达。在遇到环境数据包丢失或重新排序时，这可能导致感知延迟增加，但目标终结点将始终看到每条消息，并且按其发送的相同顺序看到。 将 SequentialDelivery 与 BestEffortDelivery 一起使用可能会导致消息被丢弃，如果某条消息乱序到达目标终结点且稍后的顺序消息已被送达，则会发生此情况。目标终结点将始终看到序列向前推进，但该序列中可能有间隙。较旧的消息永远不会在较新的消息之后传递。 |
| NonsequentialDelivery | 消息一到达就传递到目标。 使用非顺序传递选项发送的消息不提供任何有关它们相对于任何其他消息（顺序或非顺序）的传递顺序的保证。它们将在到达目标时立即传递到目标，如果环境中出现数据包丢失或重新排序，这可能与它们发送时的顺序不同。 此选项标志非常适合可以按任何顺序处理，或者已具备自身固有排序信息的消息，并且你希望获得最高的网络效率和最低的感知延迟。 如果未指定 SequentialDelivery 选项标志，则此为默认值。 |
| CopyDataBuffers | 指示 Party 库复制所提供的数据缓冲区以供后续传输。 所提供的 PartyDataBuffer 结构中的内存内容将被复制，因此调用方在 PartyLocalEndpoint::SendMessage() 返回后无需保留这些缓冲区。这比使用 DontCopyDataBuffers 选项标志更方便，但效率稍低。 如果未指定 DontCopyDataBuffers 选项标志，则此为默认值。 |
| DontCopyDataBuffers | 通知 Party 库直接使用所提供的数据缓冲区，并且调用方将在库不再需要这些内存时保持它们有效。 所提供的 PartyDataBuffer 结构引用的内存不会被复制，而是所有权将暂时转移到 Party 库，以便在传输过程中直接访问内存而无需额外的复制开销。调用方有责任确保内存缓冲区保持有效且未被修改，直到库不再需要它们，并且通过 PartyDataBuffersReturnedStateChange 将所有权转移回来。这比使用 CopyDataBuffers 选项更高效，但可能不那么方便。 PartyLocalEndpoint::SendMessage() 调用返回后，PartyDataBuffer 结构本身无需保持有效，只需其引用的内存保持有效。 |
| CoalesceOpportunistically | 指定此消息应与任何其他排队的消息合并，但如果没有等待中的消息，则不应延迟传输。 将多个消息合并到单个数据包中可以最大化带宽效率（减少每个数据包的开销），但如果为了合并而延迟消息的传输，则可能会增加消息的感知延迟。使用此标志发送会使 Party 库在有其他排队消息可用时合并该消息，但如果没有其他消息且该消息可以立即传输，则不等待更多消息。 如果通常将网络更新批量处理为单个周期性消息，且这些消息不太可能与其他消息大约同时排队，并且延迟不会带来带宽效率收益，则使用此标志。 此标志不保证消息立即开始传输。如果连接质量或接收方响应能力目前似乎不支持发送额外数据，则该消息可能会排队等待下一次传输机会。 如果未指定 AlwaysCoalesceUntilFlushed 选项标志，则此为默认值。 |
| AlwaysCoalesceUntilFlushed | 指定此消息应始终尝试与其他消息合并，并期望调用 PartyLocalEndpoint::FlushMessages() 才开始传输。 将多个消息合并到单个数据包中可以最大化带宽效率（减少每个数据包的开销），但如果为了合并而延迟消息的传输，则可能会增加消息的感知延迟。使用此标志发送会使 Party 库始终倾向于合并该消息，并延迟传输直到调用 PartyLocalEndpoint::FlushMessages()。 如果通常在同一个更新循环中向同一目标发送许多小消息，并且希望在完整更新循环迭代完成时显式通知 Party 库，请考虑使用此标志。 即使使用此标志，也存在无需显式调用 PartyLocalEndpoint::FlushMessages() 消息就可能开始传输的情况。当已存在因其他原因正在传输的其他排队消息且数据包中有空间容纳此消息时，就会发生这种情况。同样，当存在足够的消息数据字节以发送完整数据包且无法再进行合并时，将发送数据包。当所有消息已开始传输时调用 PartyLocalEndpoint::FlushMessages() 是无害的。 |
| RequireTimelyAcknowledgement | 指示此消息应及时收到确认（如果需要）。 接收方确认消息的接收以通知发送方传递成功或失败，以便发送方可以执行诸如重试包含使用 GuaranteedDelivery 选项标志发送的消息的丢弃数据包等操作。作为典型双向通信的一部分，确认通常搭载在数据包上，但如果没有数据包在回程方向流动，此标志将指示目标终结点仅等待一个小的、内部管理的超时以获取搭载机会，之后再强制发送确认数据包通知发送方。该专用数据包会消耗一些额外开销，但可确保发送方及时获得状态以进行任何必要的重试。 建议对大多数保证传递消息使用此标志。它非常适合对延迟敏感的消息。它也非常适合双向保证传递发送模式不频繁或不可预测的情况。 如果未指定 AllowLazyAcknowledgement 选项标志，则此为默认值。 如果未指定 GuaranteedDelivery 选项标志，则忽略此标志。 |
| AllowLazyAcknowledgement | 指示此消息可以在方便时（而非紧急地）收到确认。 接收方确认消息的接收以通知发送方传递成功或失败，以便发送方可以执行诸如重试包含使用 GuaranteedDelivery 选项标志发送的消息的丢弃数据包等操作。作为典型双向通信的一部分，确认通常搭载在数据包上，但如果没有数据包在回程方向流动，此标志将指示目标终结点等待搭载机会，而不强制发送确认数据包通知发送方。这会延迟发送方了解任何必要重试的状态，但避免了专用数据包所消耗的额外开销。 对于”发送后即忘”且对延迟不敏感的保证传递消息，请考虑使用此标志。当双向发送模式频繁时，它也可能减少开销。 如果同时未指定 GuaranteedDelivery 选项标志，则忽略此标志。 |
Requirements
Header: Party.hSee also
Party membersPartySendMessageQueuingConfiguration
PartyDataBuffersReturnedStateChange
PartyLocalEndpoint::SendMessage
PartyLocalEndpoint::FlushMessages