README.md

Introduction

reliable is a simple packet acknowledgement system for UDP-based protocols.

It's useful in situations where you need to know which UDP packets you sent were received by the other side.

It has the following features:

1. Acknowledgement when packets are received
2. Packet fragmentation and reassembly
3. RTT, jitter and packet loss estimates

reliable is stable and production ready.

Usage

Reliable is designed to operate with your own network socket library.

If you don't have one already, try netcode, it's designed to work well with reliable.

First, create an endpoint on each side of the connection:

struct reliable_config_t config;

reliable_default_config( &config );

config.max_packet_size = 32 * 1024;
config.fragment_above = 1200;
config.max_fragments = 32;
config.fragment_size = 1024;
config.transmit_packet_function = transmit_packet;
config.process_packet_function = process_packet;

reliable_endpoint_t * endpoint = reliable_endpoint_create( &config, time );
if ( endpoint == NULL )
{
  printf( "error: could not create endpoint\n" );
  exit(1);
}

For example, in a client/server setup you would have one endpoint on each client, and n endpoints on the server, one for each client slot.

Next, create a function to transmit packets:

static void transmit_packet( void * context, uint64_t id, uint16_t sequence, uint8_t * packet_data, int packet_bytes )
{
    // send packet using your own udp socket
}

And a function to process received packets:

static int process_packet( void * context, uint64_t id, uint16_t sequence, uint8_t * packet_data, int packet_bytes )
{
    // read the packet here and process its contents, return 0 if the packet should not be acked
    return 1;
}

For each packet you receive from your udp socket, call this on the endpoint that should receive it:

reliable_endpoint_receive_packet( endpoint, packet_data, packet_bytes );

Now you can send packets through the endpoint:

reliable_endpoint_send_packet( endpoint, packet_data, packet_bytes );

And get acks like this:

int num_acks;
uint16_t * acks = reliable_endpoint_get_acks( endpoint, &num_acks );
for ( int i = 0; i < num_acks; i++ )
{
    printf( "acked packet %d\n", acks[j] );
}

Once you process all acks, clear them:

reliable_endpoint_clear_acks( endpoint );

Before you send a packet, you can ask reliable what sequence number the sent packet will have:

uint16_t sequence = reliable_endpoint_next_packet_sequence( endpoint );

This way you can map acked sequence numbers to the contents of packets you sent, for example, resending unacked messages until a packet that included that message was acked.

Make sure to update each endpoint once per-frame. This keeps track of network stats like latency, jitter, packet loss and bandwidth:

reliable_endpoint_update( endpoint, time );

You can then grab stats from the endpoint:

    printf( rtt = %.1fms | jitter = %.1fms | packet loss = %.1f%%\n", 
        reliable_endpoint_rtt_min( endpoint ),
        reliable_endpoint_jitter_avg_vs_min_rtt( endpoint ),
        reliable_endpoint_packet_loss( endpoint ) ),

When you are finished with an endpoint, destroy it:

reliable_endpoint_destroy( endpoint );

Author

The author of this library is Glenn Fiedler.

Open source libraries by the same author include: netcode, serialize, and yojimbo

If you find this software useful, please consider sponsoring it. Thanks!

License

BSD 3-Clause license.