Menu
Lumberyard
Developer Guide (Version 1.11)

Carrier

Carrier is GridMate's messaging API. GridMate's reliable UDP implementation supports both reliable and unreliable messages. There is no out-of-order delivery. Out-of-order messages are queued if sent reliably, or discarded if sent unreliably.

The carrier sends messages through channels. The purpose of channels is to separate unrelated traffic, such as game state and voice chat. Message ordering is not enforced across channels.

The carrier API also provides hooks for congestion control and traffic simulation.

Channels and Message Priorities

Messages can be sent on different channels and have different priorities. Message ordering is always maintained between messages with the same priority sent on the same channel.

Channels provide a way to separate unrelated messages so that their ordering does not affect one other. When messages arrive out of order, they are either discarded or queued (and therefore delayed) depending on their reliability. Using different channels prevents unrelated messages from being unnecessarily dropped or delayed. For example, object replication traffic and voice chat traffic can be sent on different channels, so a missing reliable message for object replication would not cause voice chat data to be dropped, and vice versa.

Customizable Classes

You can customize the following classes to implement your own networking features:

  • Driver - Carrier defers actual network operations to the driver, so different implementations can be provided for different platforms. This abstraction makes it possible to use platform-specific protocols from service providers such as Steam. The default implementation uses UDP and supports IPv4 and IPv6.

  • Simulator - If a network simulator is present, the carrier passes all inbound and outbound traffic through it so different network conditions can be simulated. One simulator instance can be supplied per carrier instance. The default implementation can simulate different patterns for inbound and/or outbound latency, bandwidth caps, packet loss and packet reordering.

  • Traffic Control - The traffic control module has two primary functions: provide network statistics and congestion control. Whenever messages are sent or received, they are passed along to the traffic control module so it can update its statistics, and also so it can provide feedback to limit the amount of data being sent. It also decides if messages should be considered lost and resent by the carrier.

CarrierDesc

CarrierDesc is the carrier descriptor. When you create a carrier, you use the CarrierDesc structure to specify the parameters for the current session.

CarrierDesc Parameters

The following parameters can be supplied during carrier initialization:

Parameter Data Type Description
m_address const char * Specifies the local communication address to which the driver will bind. A value of 0 specifies any address. The default is nullptr.
m_connectionEvaluationThreshold float When a disconnection is detected, specifies the threshold at which all other connections are checked using m_connectionTimeoutMS * m_connectionEvaluationThreshold to see if they are also failing because of a network failure. The default is 0.5f.
m_connectionTimeoutMS unsigned int Determines the time to allow for a connection attempt. The default is 5000 milliseconds.
m_disconnectDetectionPacketLossThreshold float Packet loss percentage threshold. Possible values are from 0.0 to 1.0, where 1.0 is 100 percent. The connection will be dropped after packet loss exceeds the value specified. The default is 0.3f.
m_disconnectDetectionRttThreshold float Specifies the RTT (round-trip time) threshold in milliseconds. The connection is dropped when the measured RTT is greater than the value specified. The default is 500.0f.
m_driver class Driver * Specifies a custom driver implementation. The default is nullptr.
m_driverIsCrossPlatform bool Specifies whether the driver maintains cross-platform compatibility. When true, the default driver drops to the most restrictive MTU (maximum transmission unit) across all supported platforms. The default is false.
m_driverIsFullPackets bool Specifies whether the driver ignores MTU limits. This parameter applies only to socket drivers and local area networks. An internet packet is usually around 1500 bytes. A value of true enables a maximum packet size of 64 KB. These big packets fail on the Internet but typically do not on local networks. The default is false.
m_driverReceiveBufferSize unsigned int Specifies the size of the internal receive buffer that the driver uses. A value of 0 specifies the default buffer size. This parameter can be used only if m_driver == null. The default is 0.
m_driverSendBufferSize unsigned int Specifies the size of the internal send buffer that the driver uses. A value of 0 specifies the default buffer size. This parameter can be used only if m_driver == null. The default is 0.
m_enableDisconnectionDetection bool

Specifies whether the carrier drops connections when traffic conditions are bad. The default is true.

Note

This parameter should be set to false only when debugging.

m_familyType int Specifies the protocol family that the driver uses. A value of 0 specifies the default family.
m_port unsigned int Specifies the local communication port to which the driver binds. A value of 0 specifies the port assigned by the system.
m_securityData const char * Specifies a pointer to a string with security data. The default is nullptr.
m_simulator class Simulator * Optionally specifies a simulator through which all network messages are filtered. When specified, the carrier passes all inbound and outbound traffic through the specified simulator so that different network conditions can be simulated. You can specify one simulator instance per carrier instance.
m_threadCpuID int Restricts the carrier thread to a specific CPU core. The values that can be specified are platform dependent. A value of -1 specifies no restriction. The default is -1.
m_threadInstantResponse bool

Specifies whether IO events wake up the carrier thread immediately. The default is false.

Note

Setting this value to true typically uses more bandwidth because messages (especially small messages) are grouped less efficiently.

m_threadPriority int Specifies the thread priority for the carrier thread. The values that can be specified are platform dependent. A value of -100000 inherits the priority from calling thread. The default is -100000.
m_threadUpdateTimeMS int Specifies, in milliseconds, how often the carrier thread is updated. This parameter is ignored if m_threadInstantResponse is true. Possible values are from 0 through 100. In general, the time interval should be higher than 10 milliseconds. Otherwise, it is more efficient to set m_threadInstantResponse to true. The default is 30 milliseconds.
m_trafficControl class TrafficControl * Specifies a custom traffic control implementation that controls traffic flow to all connections and that handles issues like network congestion.
m_version VersionType

Specifies the version of Carrier API that is being used. Carriers with mismatching version numbers are not allowed to connect to each other. The default is 1.