result.h File Reference

Generic result type. More...

#include "connect.h"
#include <limits.h>
#include <stdalign.h>
#include <stddef.h>

Go to the source code of this file.

Data Structures
union	udipe_network_payload_u
struct	udipe_custom_payload_s
struct	udipe_unordered_payload_s
struct	udipe_timer_repeat_payload_s
struct	udipe_result_s

Typedefs
typedef union udipe_network_payload_u	udipe_network_payload_t
typedef struct udipe_custom_payload_s	udipe_custom_payload_t
typedef struct udipe_future_s	udipe_future_t
typedef struct udipe_unordered_payload_s	udipe_unordered_payload_t
typedef struct udipe_timer_repeat_payload_s	udipe_timer_repeat_payload_t
typedef enum udipe_result_type_e	udipe_result_type_t
typedef struct udipe_result_s	udipe_result_t

Enumerations
enum	udipe_result_type_e {   UDIPE_CONNECT = 1 , UDIPE_DISCONNECT , UDIPE_CUSTOM , UDIPE_JOIN ,   UDIPE_UNORDERED , UDIPE_TIMER_ONCE , UDIPE_TIMER_REPEAT , UDIPE_RESULT_INVALID = 0 ,   UDIPE_FAILURE_DEPENDENCY = INT_MIN , UDIPE_FAILURE_CANCELED }

Detailed Description

This header defines the udipe_result_t type, which can encapsulate the result of any of the libudipe commands defined in command.h, along with related lower-level definitions.

Typedef Documentation

udipe_custom_payload_t

typedef struct udipe_custom_payload_s udipe_custom_payload_t

Result payload from custom futures created via udipe_start_custom()

User-defined futures can return data of any type that can be encoded into the inner bytes field. If your intended result type doesn't fit in there, then you will need to either heap-allocate a memory block for it or somehow have the user pass in a memory block under their control.

udipe_network_payload_t

typedef union udipe_network_payload_u udipe_network_payload_t

Result payloads from network futures

This result payload pairs with a udipe_result_type_t that indicates what network command produced the result in question.

udipe_result_t

typedef struct udipe_result_s udipe_result_t

Generic result type

This type can encapsulate the result of any libudipe command, as well as an absence of result.

udipe_result_type_t

typedef enum udipe_result_type_e udipe_result_type_t

Result type

This enumerated type has one positive value per libudipe command. It is used to make udipe_result_t generic over all udipe command types.

In addition to one code per command, it also has sentinel values whose presence should be checked as they indicate absence of a valid result as a result of some issue. See the documentation of these sentinel values for more information.

Note that absence of a sentinel values does NOT imply that the operation was successful, only that it ran far enough to produce a result of the intended type. That result may itself be nothing but an error code. Check operation-specific result types for more information.

udipe_timer_repeat_payload_t

typedef struct udipe_timer_repeat_payload_s udipe_timer_repeat_payload_t

Result payload from repeating timer futures created via udipe_start_timer_repeat()

udipe_unordered_payload_t

typedef struct udipe_unordered_payload_s udipe_unordered_payload_t

Result payload from unordered futures created via udipe_start_unordered()

Enumeration Type Documentation

udipe_result_type_e

enum udipe_result_type_e

Result type

This enumerated type has one positive value per libudipe command. It is used to make udipe_result_t generic over all udipe command types.

In addition to one code per command, it also has sentinel values whose presence should be checked as they indicate absence of a valid result as a result of some issue. See the documentation of these sentinel values for more information.

Note that absence of a sentinel values does NOT imply that the operation was successful, only that it ran far enough to produce a result of the intended type. That result may itself be nothing but an error code. Check operation-specific result types for more information.

Enumerator
UDIPE_CONNECT	udipe_start_connect()
UDIPE_DISCONNECT	udipe_start_disconnect()
UDIPE_CUSTOM	udipe_start_custom()
UDIPE_JOIN	udipe_start_join()
UDIPE_UNORDERED	udipe_start_unordered()
UDIPE_TIMER_ONCE	udipe_start_timer_once()
UDIPE_TIMER_REPEAT	udipe_start_timer_repeat()
UDIPE_RESULT_INVALID	Invalid result type This result type should never be observed by user code, and its presence is a direct indication that either the application or udipe has a bug. \internal Every freshly zero-initialized command identifier gets this sentinel value and every allocatable struct that contains a command identifier sets it back to this value upon liberation. This helps with the detection of several kinds of invalid struct usage: - Incorrectly initialized struct (every initialized struct should have its command ID set to a different value). - Use-after-free (a freed struct's command ID gets back to this value) - Double allocation (after allocation, a struct's command ID gets configured to a different value). These checks are typically reserved to Debug builds, but for operations that are not critical to runtime performance they can be performed in Release builds too.
UDIPE_FAILURE_DEPENDENCY	No result because this operation depends on a failed operation This result type can be observed for commands that are scheduled to execute after other futures complete, such as network commands and udipe_start_join(). It is set when such upstream work has failed, and therefore the work associated with this future (if any) could not even start executing, let alone produce a normal result.
UDIPE_FAILURE_CANCELED	No result because this operation was canceled This result type is observed when a future is passed to udipe_cancel(). In this case, the operation may not run to completion, and is therefore not guaranteed to produce a normal result.