command.h File Reference

Worker thread commands. More...

#include "connect.h"
#include "context.h"
#include "future.h"
#include "nodiscard.h"
#include "pointer.h"
#include "result.h"
#include "visibility.h"
#include <assert.h>

Go to the source code of this file.

Functions
UDIPE_NODISCARD UDIPE_NON_NULL_ARGS UDIPE_NON_NULL_RESULT UDIPE_PUBLIC udipe_future_t *	udipe_start_connect (udipe_context_t *context, udipe_connect_options_t options)
UDIPE_NODISCARD UDIPE_NON_NULL_ARGS UDIPE_PUBLIC udipe_connect_result_t	udipe_connect (udipe_context_t *context, udipe_connect_options_t options)
UDIPE_NODISCARD UDIPE_NON_NULL_ARGS UDIPE_NON_NULL_RESULT UDIPE_PUBLIC udipe_future_t *	udipe_start_disconnect (udipe_context_t *context, udipe_disconnect_options_t options)
UDIPE_NODISCARD UDIPE_NON_NULL_ARGS UDIPE_PUBLIC udipe_disconnect_result_t	udipe_disconnect (udipe_context_t *context, udipe_disconnect_options_t options)

Detailed Description

In libudipe, UDP communication is performed by sending commands to worker threads, which asynchronously process them.

The use of dedicated worker threads lets libudipe internally follow many best practices for optimal UDP performance, without forcing your application threads that interact with libudipe into the same discipline. But there is a price to pay, which is that individual commands are rather expensive to process as they involve inter-thread communication.

This is why most commands that process a single UDP datagram come with a streaming variant that processes an arbitrarily long stream of UDP datagrams. For example, udipe_recv(), which receives a single UDP datagram, comes with a udipe_recv_stream() streaming variant that processes an arbitrary amount of incoming UDP datagrams using arbitrary logic defined by a callback.

These callbacks are directly executed by libudipe worker threads, which means that they operate without requiring any inter-thread communication. But this also means that they also require careful programming practices when top performance is desired. See the documentation of individual streaming functions for more advice on how to do this.

Finally, all commands come with two associated API entry points, a synchronous one and an asynchronous one. For example, the udipe_recv() entry point, which receives a UDP datagram, comes with a udipe_start_recv() asynchronous variant which starts receiving a UDP datagram but does not wait for it to be ready before returning. See future.h for more information of how these asynchronous commands work.