#include <stdint.h>
#include <stdbool.h>
#include <stdarg.h>
#include <sys/uio.h>
#include <sys/types.h>

Include dependency graph for object.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	RPC_ARRAY_APPLIER(_fn, _arg)

#define	RPC_DICTIONARY_APPLIER(_fn, _arg)

#define	RPC_ARRAY_CMP(_fn, _arg)

#define	RPC_BINARY_DESTRUCTOR(_fn)

#define	RPC_BINARY_DESTRUCTOR_ARG(_fn, _arg)

#define	rpc_is_error(_object) (rpc_get_type(_object) == RPC_TYPE_ERROR)

#define	rpc_release(_object)

#define	rpc_swap(_old, _new)

#define	rpc_auto_object_t __attribute__((cleanup(__rpc_raii_release))) rpc_object_t

Typedefs
typedef struct rpc_object *	rpc_object_t

typedef bool(^	rpc_array_applier_t) (size_t index, _Nonnull rpc_object_t value)

typedef _Nonnull rpc_object_t(^	rpc_array_mapper_t) (size_t index, _Nonnull rpc_object_t value)

typedef bool(^	rpc_dictionary_applier_t) (const char *_Nonnull key, _Nonnull rpc_object_t value)

typedef _Nonnull rpc_object_t(^	rpc_dictionary_mapper_t) (const char *_Nonnull key, _Nonnull rpc_object_t value)

typedef int(^	rpc_array_cmp_t) (_Nonnull rpc_object_t o1, _Nonnull rpc_object_t o2)

typedef void(^	rpc_binary_destructor_t) (void *_Nullable)

Enumerations
enum	rpc_type_t { RPC_TYPE_NULL, RPC_TYPE_BOOL, RPC_TYPE_UINT64, RPC_TYPE_INT64, RPC_TYPE_DOUBLE, RPC_TYPE_DATE, RPC_TYPE_STRING, RPC_TYPE_BINARY, RPC_TYPE_FD, RPC_TYPE_DICTIONARY, RPC_TYPE_ARRAY, RPC_TYPE_ERROR }

Functions
_Nonnull rpc_object_t	rpc_retain (_Nonnull rpc_object_t object)

int	rpc_release_impl (_Nonnull rpc_object_t object)

int	rpc_get_refcount (_Nullable rpc_object_t object)

size_t	rpc_get_line_number (_Nonnull rpc_object_t object)

size_t	rpc_get_column_number (_Nonnull rpc_object_t object)

_Nonnull rpc_object_t	rpc_copy (_Nonnull rpc_object_t object)

int	rpc_cmp (_Nullable rpc_object_t o1, _Nullable rpc_object_t o2)

bool	rpc_equal (_Nullable rpc_object_t o1, _Nullable rpc_object_t o2)

size_t	rpc_hash (_Nonnull rpc_object_t object)

char *_Nonnull	rpc_copy_description (_Nonnull rpc_object_t object)

rpc_type_t	rpc_get_type (_Nonnull rpc_object_t object)

const char *_Nullable	rpc_get_type_name (rpc_type_t type)

_Nullable rpc_object_t	rpc_get_last_error (void)

_Nullable rpc_object_t	rpc_object_pack (const char *_Nonnull fmt,...)

_Nullable rpc_object_t	rpc_object_vpack (const char *_Nonnull fmt, va_list ap)

int	rpc_object_unpack (_Nonnull rpc_object_t, const char *_Nonnull fmt,...)

int	rpc_object_vunpack (_Nonnull rpc_object_t, const char *_Nonnull fmt, va_list ap)

_Nonnull rpc_object_t	rpc_null_create (void)

_Nonnull rpc_object_t	rpc_bool_create (bool value)

bool	rpc_bool_get_value (_Nonnull rpc_object_t xbool)

_Nonnull rpc_object_t	rpc_int64_create (int64_t value)

int64_t	rpc_int64_get_value (_Nonnull rpc_object_t xint)

_Nonnull rpc_object_t	rpc_uint64_create (uint64_t value)

uint64_t	rpc_uint64_get_value (_Nonnull rpc_object_t xuint)

_Nonnull rpc_object_t	rpc_double_create (double value)

double	rpc_double_get_value (_Nonnull rpc_object_t xdouble)

_Nonnull rpc_object_t	rpc_date_create (int64_t interval)

_Nonnull rpc_object_t	rpc_date_create_from_current (void)

int64_t	rpc_date_get_value (_Nonnull rpc_object_t xdate)

_Nonnull rpc_object_t	rpc_data_create (const void *_Nullable bytes, size_t length, _Nullable rpc_binary_destructor_t destructor)

_Nonnull rpc_object_t	rpc_data_create_iov (struct iovec *_Nonnull iov, size_t niov)

size_t	rpc_data_get_length (_Nonnull rpc_object_t xdata)

const void *_Nullable	rpc_data_get_bytes_ptr (_Nonnull rpc_object_t xdata)

size_t	rpc_data_get_bytes (_Nonnull rpc_object_t xdata, void *_Nonnull buffer, size_t off, size_t length)

_Nonnull rpc_object_t	rpc_string_create (const char *_Nonnull string)

_Nonnull rpc_object_t	rpc_string_create_len (const char *_Nonnull string, size_t length)

_Nonnull rpc_object_t	rpc_string_create_with_format (const char *_Nonnull fmt,...)

_Nonnull rpc_object_t	rpc_string_create_with_format_and_arguments (const char *_Nonnull fmt, va_list ap)

size_t	rpc_string_get_length (_Nonnull rpc_object_t xstring)

const char *_Nullable	rpc_string_get_string_ptr (_Nonnull rpc_object_t xstring)

_Nonnull rpc_object_t	rpc_fd_create (int fd)

int	rpc_fd_dup (_Nonnull rpc_object_t xfd)

int	rpc_fd_get_value (_Nonnull rpc_object_t xfd)

_Nonnull rpc_object_t	rpc_array_create (void)

_Nonnull rpc_object_t	rpc_array_create_ex (const _Nonnull rpc_object_t *_Nonnull objects, size_t count, bool steal)

void	rpc_array_set_value (_Nonnull rpc_object_t array, size_t index, _Nullable rpc_object_t value)

void	rpc_array_steal_value (_Nonnull rpc_object_t array, size_t index, _Nullable rpc_object_t value)

void	rpc_array_remove_index (_Nonnull rpc_object_t array, size_t index)

void	rpc_array_remove_all (_Nonnull rpc_object_t array)

void	rpc_array_append_value (_Nonnull rpc_object_t array, _Nonnull rpc_object_t value)

void	rpc_array_append_stolen_value (_Nonnull rpc_object_t array, _Nonnull rpc_object_t value)

_Nullable rpc_object_t	rpc_array_get_value (_Nonnull rpc_object_t array, size_t index)

size_t	rpc_array_get_count (_Nonnull rpc_object_t array)

bool	rpc_array_apply (_Nonnull rpc_object_t array, _Nonnull rpc_array_applier_t applier)

void	rpc_array_map (_Nonnull rpc_object_t array, _Nonnull rpc_array_mapper_t mapper)

bool	rpc_array_contains (_Nonnull rpc_object_t array, _Nonnull rpc_object_t value)

bool	rpc_array_reverse_apply (_Nonnull rpc_object_t array, _Nonnull rpc_array_applier_t applier)

void	rpc_array_sort (_Nonnull rpc_object_t array, _Nonnull rpc_array_cmp_t comparator)

_Nonnull rpc_object_t	rpc_array_slice (_Nonnull rpc_object_t array, size_t start, ssize_t len)

void	rpc_array_set_bool (_Nonnull rpc_object_t array, size_t index, bool value)

void	rpc_array_set_int64 (_Nonnull rpc_object_t array, size_t index, int64_t value)

void	rpc_array_set_uint64 (_Nonnull rpc_object_t array, size_t index, uint64_t value)

void	rpc_array_set_double (_Nonnull rpc_object_t array, size_t index, double value)

void	rpc_array_set_date (_Nonnull rpc_object_t array, size_t index, int64_t value)

void	rpc_array_set_data (_Nonnull rpc_object_t array, size_t index, const void *_Nullable bytes, size_t length)

void	rpc_array_set_string (_Nonnull rpc_object_t array, size_t index, const char *_Nonnull value)

void	rpc_array_set_fd (_Nonnull rpc_object_t array, size_t index, int value)

bool	rpc_array_get_bool (_Nonnull rpc_object_t array, size_t index)

int64_t	rpc_array_get_int64 (_Nonnull rpc_object_t array, size_t index)

uint64_t	rpc_array_get_uint64 (_Nonnull rpc_object_t array, size_t index)

double	rpc_array_get_double (_Nonnull rpc_object_t array, size_t index)

int64_t	rpc_array_get_date (_Nonnull rpc_object_t array, size_t index)

const void *_Nullable	rpc_array_get_data (_Nonnull rpc_object_t array, size_t index, size_t *_Nullable length)

const char *_Nullable	rpc_array_get_string (_Nonnull rpc_object_t array, size_t index)

int	rpc_array_get_fd (_Nonnull rpc_object_t array, size_t index)

int	rpc_array_dup_fd (_Nonnull rpc_object_t array, size_t index)

_Nonnull rpc_object_t	rpc_error_create (int code, const char *_Nonnull msg, _Nullable rpc_object_t extra)

_Nonnull rpc_object_t	rpc_error_create_with_stack (int code, const char *_Nonnull msg, _Nullable rpc_object_t extra, _Nullable rpc_object_t stack)

int	rpc_error_get_code (_Nonnull rpc_object_t error)

const char *_Nullable	rpc_error_get_message (_Nonnull rpc_object_t error)

_Nullable rpc_object_t	rpc_error_get_extra (_Nonnull rpc_object_t error)

void	rpc_error_set_extra (_Nonnull rpc_object_t error, _Nonnull rpc_object_t extra)

_Nullable rpc_object_t	rpc_error_get_stack (_Nonnull rpc_object_t error)

_Nonnull rpc_object_t	rpc_dictionary_create (void)

_Nonnull rpc_object_t	rpc_dictionary_create_ex (const char const _Nonnull _Nullable keys, const _Nonnull rpc_object_t *_Nullable values, size_t count, bool steal)

void	rpc_dictionary_set_value (_Nonnull rpc_object_t dictionary, const char *_Nonnull key, _Nonnull rpc_object_t value)

void	rpc_dictionary_steal_value (_Nonnull rpc_object_t dictionary, const char *_Nonnull key, rpc_object_t _Nonnull value)

void	rpc_dictionary_remove_key (_Nonnull rpc_object_t dictionary, const char *_Nonnull key)

void	rpc_dictionary_remove_all (_Nonnull rpc_object_t dictionary)

_Nullable rpc_object_t	rpc_dictionary_detach_key (_Nonnull rpc_object_t dictionary, const char *_Nonnull key)

_Nullable rpc_object_t	rpc_dictionary_get_value (_Nonnull rpc_object_t dictionary, const char *_Nonnull key)

size_t	rpc_dictionary_get_count (_Nonnull rpc_object_t dictionary)

bool	rpc_dictionary_apply (_Nonnull rpc_object_t dictionary, _Nonnull rpc_dictionary_applier_t applier)

void	rpc_dictionary_map (_Nonnull rpc_object_t dictionary, _Nonnull rpc_dictionary_mapper_t mapper)

bool	rpc_dictionary_has_key (_Nonnull rpc_object_t dictionary, const char *_Nonnull key)

void	rpc_dictionary_set_bool (_Nonnull rpc_object_t dictionary, const char *_Nonnull key, bool value)

void	rpc_dictionary_set_int64 (_Nonnull rpc_object_t dictionary, const char *_Nonnull key, int64_t value)

void	rpc_dictionary_set_uint64 (_Nonnull rpc_object_t dictionary, const char *_Nonnull key, uint64_t value)

void	rpc_dictionary_set_double (_Nonnull rpc_object_t dictionary, const char *_Nonnull key, double value)

void	rpc_dictionary_set_date (_Nonnull rpc_object_t dictionary, const char *_Nonnull key, int64_t value)

void	rpc_dictionary_set_data (_Nonnull rpc_object_t dictionary, const char _Nonnull key, const void _Nonnull value, size_t length)

void	rpc_dictionary_set_string (_Nonnull rpc_object_t dictionary, const char _Nonnull key, const char _Nonnull value)

void	rpc_dictionary_set_fd (_Nonnull rpc_object_t dictionary, const char *_Nonnull key, int value)

bool	rpc_dictionary_get_bool (_Nonnull rpc_object_t dictionary, const char *_Nonnull key)

int64_t	rpc_dictionary_get_int64 (_Nonnull rpc_object_t dictionary, const char *_Nonnull key)

uint64_t	rpc_dictionary_get_uint64 (_Nonnull rpc_object_t dictionary, const char *_Nonnull key)

double	rpc_dictionary_get_double (_Nonnull rpc_object_t dictionary, const char *_Nonnull key)

int64_t	rpc_dictionary_get_date (_Nonnull rpc_object_t dictionary, const char *_Nonnull key)

const void *_Nullable	rpc_dictionary_get_data (_Nonnull rpc_object_t dictionary, const char _Nonnull key, size_t _Nullable length)

const char *_Nullable	rpc_dictionary_get_string (_Nonnull rpc_object_t dictionary, const char *_Nonnull key)

int	rpc_dictionary_get_fd (_Nonnull rpc_object_t dictionary, const char *_Nonnull key)

int	rpc_dictionary_dup_fd (_Nonnull rpc_object_t dictionary, const char *_Nonnull key)

Detailed Description

Object model (boxed types) API.

Definition in file object.h.

Macro Definition Documentation

◆ RPC_ARRAY_APPLIER

#define RPC_ARRAY_APPLIER	(	_fn,
		_arg
	)

Value:

^(size_t _index, rpc_object_t _value) {             \
                return ((bool)_fn(_arg, _index, _value));       \
        }

Converts function pointer to an rpc_array_applier_t block type.

Definition at line 142 of file object.h.

◆ RPC_ARRAY_CMP

#define RPC_ARRAY_CMP	(	_fn,
		_arg
	)

Value:

^(rpc_object_t _o1, rpc_object_t _o2) {             \
                return ((int)_fn(_arg, _o1, _o2));          \
        }

Converts function pointer to an rpc_array_cmp_t block type.

Definition at line 158 of file object.h.

◆ rpc_auto_object_t

#define rpc_auto_object_t __attribute__((cleanup(__rpc_raii_release))) rpc_object_t

RAII version of rpc_object_t. Automatically released when goes out of scope.

Definition at line 1678 of file object.h.

◆ RPC_BINARY_DESTRUCTOR

#define RPC_BINARY_DESTRUCTOR ( _fn )

Value:

^(void *block) {                        \
        _fn(block);                     \
    }

Converts function pointer to an rpc_binary_destructor_t block type.

Definition at line 166 of file object.h.

◆ RPC_BINARY_DESTRUCTOR_ARG

#define RPC_BINARY_DESTRUCTOR_ARG	(	_fn,
		_arg
	)

Value:

^(void *_block) {                       \
        _fn(_arg, _block);                  \
    }

Same as RPC_BINARY_DESTRUCTOR, but accepts an auxiliary arg.

Definition at line 174 of file object.h.

◆ RPC_DICTIONARY_APPLIER

#define RPC_DICTIONARY_APPLIER	(	_fn,
		_arg
	)

Value:

^(const char *_key, rpc_object_t _value) {          \
                return ((bool)_fn(_arg, _key, _value));         \
        }

Converts function pointer to an rpc_dictionary_applier_t block type.

Definition at line 150 of file object.h.

◆ rpc_is_error

#define rpc_is_error ( _object ) (rpc_get_type(_object) == RPC_TYPE_ERROR)

Checks if an object is of type RPC_TYPE_ERROR.

Parameters

object Object to check.

Definition at line 313 of file object.h.

◆ rpc_release

#define rpc_release ( _object )

Value:

do {                                \
        if (rpc_release_impl(_object) == 0)         \
            (_object) = NULL;               \
    } while(0)

Decrements reference count of an object.

Also sets it to NULL if as a result of the operation reference count dropped to 0 and the object was freed.

Parameters

_object Object to release.

Examples:: client.c, fd-client.c, loopback.c, and query.c.

Definition at line 323 of file object.h.

◆ rpc_swap

#define rpc_swap	(	_old,
		_new
	)

Value:

do {                                \
        rpc_release(_old);                  \
        (_old) = (_new);                    \
    } while (0)

Swaps _old object with object.

Releases _old before replacing it with _new.

Definition at line 334 of file object.h.

Typedef Documentation

◆ rpc_array_applier_t

typedef bool(^ rpc_array_applier_t) (size_t index, _Nonnull rpc_object_t value)

Definition of array applier block type.

Body of block is being executed for each of the array's elements, until generator reaches end of the array, or until applier block returns false.

Parameters

index	Currently processed index.
value	Object stored at currently processed index.

Returns: Continue iteration signal.

Definition at line 85 of file object.h.

◆ rpc_array_cmp_t

typedef int(^ rpc_array_cmp_t) (_Nonnull rpc_object_t o1, _Nonnull rpc_object_t o2)

Definition of array compare block type.

Body of block is being executed for pairs of array's members during sort operation.

The block should return a negative integer if the first value comes before the second, 0 if they are equal, or a positive integer if the first value comes after the second.

Parameters

o1	A value.
o2	A value to compare with.

Returns: Negative value if a < b; zero if a = b; positive value if a > b.

Definition at line 127 of file object.h.

◆ rpc_binary_destructor_t

typedef void(^ rpc_binary_destructor_t) (void *_Nullable)

Definition of binary block destructor type.

This block is called every time an rpc_object_t of type BINARY is about to be freed. It must free the data buffer associated with the object.

Definition at line 137 of file object.h.

◆ rpc_dictionary_applier_t

typedef bool(^ rpc_dictionary_applier_t) (const char *_Nonnull key, _Nonnull rpc_object_t value)

Definition of dictionary applier block type.

Body of block is being executed for each of the dictionary's elements, until generator reaches end of the dictionary, or until applier block returns false.

Parameters

key	Currently processed key.
value	Object stored at currently processed key.

Returns: Continue iteration signal.

Definition at line 104 of file object.h.

◆ rpc_object_t

typedef struct rpc_object* rpc_object_t

Definition of data object pointer.

Definition at line 73 of file object.h.

Enumeration Type Documentation

◆ rpc_type_t

enum rpc_type_t

Enumerates the possible types of an rpc_object_t.

Enumerator
RPC_TYPE_NULL	null type
RPC_TYPE_BOOL	boolean type
RPC_TYPE_UINT64	unsigned 64-bit integer type
RPC_TYPE_INT64	signed 64-bit integer type
RPC_TYPE_DOUBLE	double precision floating-point type
RPC_TYPE_DATE	date type (represented as 64-bit timestamp
RPC_TYPE_STRING	string type
RPC_TYPE_BINARY	binary data type
RPC_TYPE_FD	file descriptor type
RPC_TYPE_DICTIONARY	dictionary type
RPC_TYPE_ARRAY	array type
RPC_TYPE_ERROR	error type

Definition at line 52 of file object.h.

Function Documentation

◆ rpc_array_append_stolen_value()

void rpc_array_append_stolen_value	(	_Nonnull rpc_object_t	array,
		_Nonnull rpc_object_t	value
	)

Appends an object at the end of a provided array.

Parameters

array	Input array.
value	Object to be appended.

◆ rpc_array_append_value()

void rpc_array_append_value	(	_Nonnull rpc_object_t	array,
		_Nonnull rpc_object_t	value
	)

Appends an object at the end of a provided array and increments object's refcount.

Parameters

array	Input array.
value	Object to be appended.

◆ rpc_array_apply()

bool rpc_array_apply	(	_Nonnull rpc_object_t	array,
		_Nonnull rpc_array_applier_t	applier
	)

Iterates over a given array. For each of elements executes an applier block, providing a current index and a current value an an applier block's arguments.

If an applier returns false, iteration is terminated and the function returns true (terminated). Otherwise the function iterates to the end of an input array and returns false (finished).

Parameters

array	Input array.
applier	Block of code to be executed for each array element.

Returns: Iteration terminated (true)/finished (false) boolean flag.

◆ rpc_array_contains()

bool rpc_array_contains	(	_Nonnull rpc_object_t	array,
		_Nonnull rpc_object_t	value
	)

Checks if an entry with the same value as provided in the second argument of the function exists in a given array.

The function returns boolean result of that check.

Parameters

array	Array to be searched.
value	RPC object representing value of a searched object.

Returns: Boolean result of the search operation.

◆ rpc_array_create()

_Nonnull rpc_object_t rpc_array_create ( void )

Creates a new, empty array of objects.

Returns: Empty array.

Examples:: client.c.

◆ rpc_array_create_ex()

_Nonnull rpc_object_t rpc_array_create_ex	(	const _Nonnull rpc_object_t *_Nonnull	objects,
		size_t	count,
		bool	steal
	)

Creates a new array of objects, optionally populating it with data.

Parameters

objects	Array of objects to insert.
count	Number of items in `objects`.
steal	Reference vs. reference and increment refcount of elements in `objects`.

Returns: Newly created object.

◆ rpc_array_dup_fd()

int rpc_array_dup_fd	(	_Nonnull rpc_object_t	array,
		size_t	index
	)

Duplicates a file descriptor from a given index of an input array.

If a selected index does not exist, or object being held at a given index has a type different from expected (RPC_TYPE_FD), then the function returns 0.

Parameters

array	Input array.
index	File descriptor's index.

Returns: Duplicated file descriptor (integer).

◆ rpc_array_get_bool()

bool rpc_array_get_bool	(	_Nonnull rpc_object_t	array,
		size_t	index
	)

Returns a value from a given index of an input array.

If a selected index does not exist, or object being held at a given index has a type different from expected (RPC_TYPE_BOOL), then the function returns false.

Parameters

array	Input array.
index	Index storing an output value.

Returns: Boolean value.

◆ rpc_array_get_count()

size_t rpc_array_get_count ( _Nonnull rpc_object_t array )

Returns a number of elements in a provided array.

Parameters

array Input array.

Returns: Number of elements held by an input array.

◆ rpc_array_get_data()

const void* _Nullable rpc_array_get_data	(	_Nonnull rpc_object_t	array,
		size_t	index,
		size_t *_Nullable	length
	)

Returns a value from a given index of an input array.

If a selected index does not exist, or object being held at a given index has a type different from expected (RPC_TYPE_BINARY), then the function returns NULL.

Parameters

array	Input array.
index	Output value's index.
length	Size of an output buffer.

Returns: Binary output buffer pointer.

◆ rpc_array_get_date()

int64_t rpc_array_get_date	(	_Nonnull rpc_object_t	array,
		size_t	index
	)

Returns a value from a given index of an input array.

If a selected index does not exist, or object being held at a given index has a type different from expected (RPC_TYPE_DATE), then the function returns 0.

Parameters

array	Input array.
index	Index storing an output value.

Returns: Integer representing a UNIX timestamp.

◆ rpc_array_get_double()

double rpc_array_get_double	(	_Nonnull rpc_object_t	array,
		size_t	index
	)

Returns a value from a given index of an input array.

If a selected index does not exist, or object being held at a given index has a type different from expected (RPC_TYPE_DOUBLE), then the function returns 0.

Parameters

array	Input array.
index	Index storing an output value.

Returns: Double value.

◆ rpc_array_get_fd()

int rpc_array_get_fd	(	_Nonnull rpc_object_t	array,
		size_t	index
	)

Returns a value from a given index of an input array.

If a selected index does not exist, or object being held at a given index has a type different from expected (RPC_TYPE_FD), then the function returns 0.

Parameters

array	Input array.
index	Index storing an output value.

Returns: File descriptor value (integer).

◆ rpc_array_get_int64()

int64_t rpc_array_get_int64	(	_Nonnull rpc_object_t	array,
		size_t	index
	)

Returns a value from a given index of an input array.

If a selected index does not exist, or object being held at a given index has a type different from expected (RPC_TYPE_INT64), then the function returns 0.

Parameters

array	Input array.
index	Index storing an output value.

Returns: 64-bit signed integer value.

◆ rpc_array_get_string()

const char* _Nullable rpc_array_get_string	(	_Nonnull rpc_object_t	array,
		size_t	index
	)

Returns a value from a given index of an input array.

If a selected index does not exist, or object being held at a given index has a type different from expected (RPC_TYPE_STRING), then the function returns NULL.

Parameters

array	Input array.
index	Index storing an output value.

Returns: String value.

Examples:: server.c.

◆ rpc_array_get_uint64()

uint64_t rpc_array_get_uint64	(	_Nonnull rpc_object_t	array,
		size_t	index
	)

Returns a value from a given index of an input array.

If a selected index does not exist, or object being held at a given index has a type different from expected (RPC_TYPE_UINT64), then the function returns 0.

Parameters

array	Input array.
index	Index storing an output value.

Returns: 64-bit unsigned integer value.

◆ rpc_array_get_value()

_Nullable rpc_object_t rpc_array_get_value	(	_Nonnull rpc_object_t	array,
		size_t	index
	)

Returns an object held by a provided array at a given index.

If a given index does not exist, then the function returns NULL.

Parameters

array	Input array.
index	Index of an object to be returned.

Returns: Object at a given index.

◆ rpc_array_map()

void rpc_array_map	(	_Nonnull rpc_object_t	array,
		_Nonnull rpc_array_mapper_t	mapper
	)

Iterates over a given array and replaces each element of said array with a result of mapper block.

Parameters

array	Input array
mapper	Block of code to be executed for each array element

◆ rpc_array_remove_all()

void rpc_array_remove_all ( _Nonnull rpc_object_t array )

Removes all objects from a provided array.

Parameters

array Input array.

◆ rpc_array_remove_index()

void rpc_array_remove_index	(	_Nonnull rpc_object_t	array,
		size_t	index
	)

Removes an object from a given index of a provided array.

Parameters

array	Input array.
index	Index to be removed.

◆ rpc_array_reverse_apply()

bool rpc_array_reverse_apply	(	_Nonnull rpc_object_t	array,
		_Nonnull rpc_array_applier_t	applier
	)

Iterates over a given array in reversed order (starting from its end). Besides of that the function is acting exactly the same as rpc_array_apply.

Parameters

array	Input array.
applier	Block of code to be executed for each of an array's elements.

Returns: Iteration terminated (true)/finished (false) boolean flag.

◆ rpc_array_set_bool()

void rpc_array_set_bool	(	_Nonnull rpc_object_t	array,
		size_t	index,
		bool	value
	)

Sets a selected index of an input array to a newly created RPC object holding a given boolean value.

If a selected index is larger than an input array size, then a gap between a last existing index and a requested index is filled with NULL objects.

Parameters

array	Input array.
index	Index to store an input value.
value	Input value (boolean).

◆ rpc_array_set_data()

void rpc_array_set_data	(	_Nonnull rpc_object_t	array,
		size_t	index,
		const void *_Nullable	bytes,
		size_t	length
	)

Sets a selected index of an input array to a newly created RPC object holding a given binary data of a specified length.

If a selected index is larger than an input array size, then a gap between a last existing index and a requested index is filled with NULL objects.

Parameters

array	Input array.
index	Index to store an input value.
bytes	Input binary data buffer.
length	Size of an input data buffer.

◆ rpc_array_set_date()

void rpc_array_set_date	(	_Nonnull rpc_object_t	array,
		size_t	index,
		int64_t	value
	)

Sets a selected index of an input array to a newly created RPC object holding a given UNIX timestamp value represented as an integer.

If a selected index is larger than an input array size, then a gap between a last existing index and a requested index is filled with NULL objects.

Parameters

array	Input array.
index	Index to store an input value.
value	Input value (UNIX timestamp represented as an integer).

◆ rpc_array_set_double()

void rpc_array_set_double	(	_Nonnull rpc_object_t	array,
		size_t	index,
		double	value
	)

Sets a selected index of an input array to a newly created RPC object holding a given double value.

If a selected index is larger than an input array size, then a gap between a last existing index and a requested index is filled with NULL objects.

Parameters

array	Input array.
index	Index to store an input value.
value	Input value (double).

◆ rpc_array_set_fd()

void rpc_array_set_fd	(	_Nonnull rpc_object_t	array,
		size_t	index,
		int	value
	)

Sets a selected index of an input array to a newly created RPC object holding a given file descriptor value.

If a selected index is larger than an input array size, then a gap between a last existing index and a requested index is filled with NULL objects.

Parameters

array	Input array.
index	Index to store an input value.
value	Input file descriptor (integer).

◆ rpc_array_set_int64()

void rpc_array_set_int64	(	_Nonnull rpc_object_t	array,
		size_t	index,
		int64_t	value
	)

Sets a selected index of an input array to a newly created RPC object holding a given 64-bit signed integer value.

If a selected index is larger than an input array size, then a gap between a last existing index and a requested index is filled with NULL objects.

Parameters

array	Input array.
index	Index to store an input value.
value	Input value (64-bit signed integer).

◆ rpc_array_set_string()

void rpc_array_set_string	(	_Nonnull rpc_object_t	array,
		size_t	index,
		const char *_Nonnull	value
	)

Sets a selected index of an input array to a newly created RPC object holding a given string value.

If a selected index is larger than an input array size, then a gap between a last existing index and a requested index is filled with NULL objects.

Parameters

array	Input array.
index	Index to store an input value.
value	Input string (null byte terminated constant character pointer).

◆ rpc_array_set_uint64()

void rpc_array_set_uint64	(	_Nonnull rpc_object_t	array,
		size_t	index,
		uint64_t	value
	)

Sets a selected index of an input array to a newly created RPC object holding a given 64-bit unsigned integer value.

If a selected index is larger than an input array size, then a gap between a last existing index and a requested index is filled with NULL objects.

Parameters

array	Input array.
index	Index to store an input value.
value	Input value (64-bit unsigned integer).

◆ rpc_array_set_value()

void rpc_array_set_value	(	_Nonnull rpc_object_t	array,
		size_t	index,
		_Nullable rpc_object_t	value
	)

Inserts an object to array at index and increments value refcount.

If index is bigger than the array itself, gap will be filled with null objects.

If index is already occupied, then a new object takes place of an old object and the refcount of an old object is decremented.

If array is NULL, then this function removes an old object from index.

Parameters

array	Input array.
value	Value to be inserted.
index	Target index for a newly inserted value.

◆ rpc_array_slice()

_Nonnull rpc_object_t rpc_array_slice	(	_Nonnull rpc_object_t	array,
		size_t	start,
		ssize_t	len
	)

Takes an input array and copies a selected number of its elements, starting from a given index, creating an output array.

If a copy size is set to -1, then an output array is being created from input array's elements from a start index to the end of an input array.

If during a copy operation, the end of an input array is reached before size requirement is satisfied, then a copy operation is terminated and the function returns an array smaller than a requested size.

Parameters

array	Input array.
start	Copy start index.
len	Requested copy size.

Returns: Newly created array containing elements copied from an input array.

◆ rpc_array_sort()

void rpc_array_sort	(	_Nonnull rpc_object_t	array,
		_Nonnull rpc_array_cmp_t	comparator
	)

Sorts contents of a given array using provided comparator code block.

The desired behavior of the comparator block is described in rpc_array_cmp_t type's documentation.

Parameters

array	Array to be sorted.
comparator	Comparator to be used during sort operation.

◆ rpc_array_steal_value()

void rpc_array_steal_value	(	_Nonnull rpc_object_t	array,
		size_t	index,
		_Nullable rpc_object_t	value
	)

Inserts an object to an input array at a given index.

If an index is bigger than an array itself, gap will be filled with null objects.

If an index is already occupied, then a new object takes place of an old object and the refcount of an old object is decremented.

If an object is NULL, then this function removes an old object from a given index.

Parameters

array	Input array.
value	Value to be inserted.
index	Target index for a newly inserted value.

◆ rpc_bool_create()

_Nonnull rpc_object_t rpc_bool_create ( bool value )

Creates an rpc_object_t holding boolean value.

Parameters

value Value of the object (true or false).

Returns: Newly created object.

Examples:: query.c.

◆ rpc_bool_get_value()

bool rpc_bool_get_value ( _Nonnull rpc_object_t xbool )

Returns a boolean value of an object.

If rpc_object_t passed as the first argument if not of RPC_TYPE_BOOL type, the function returns false.

Parameters

xbool Object to read the value from.

Returns: Boolean value of the object (true or false).

◆ rpc_cmp()

int rpc_cmp	(	_Nullable rpc_object_t	o1,
		_Nullable rpc_object_t	o2
	)

Compares objects provided as the function arguments and returns the comparison result.

The function returns negative value if object passed in first argument is smaller than the object passed in the second argument.

The function returns zero if object passed in first argument is equal to the object passed in the second argument.

The function returns positive value if object passed in first argument is greater than the object passed in the second argument.

Parameters

o1	Object to be compared.
o2	Object to be compared.

Returns: Negative value - o1 < o2, zero - o1 = o2, positive value - o1 > o2

◆ rpc_copy()

_Nonnull rpc_object_t rpc_copy ( _Nonnull rpc_object_t object )

Creates and returns independent copy of an object.

Parameters

object Object to be copied.

Returns: Copy of an provided as the function argument.

◆ rpc_copy_description()

char* _Nonnull rpc_copy_description ( _Nonnull rpc_object_t object )

Creates and returns null byte terminated human readable string representation of an object.

Caller has to take care of releasing resources held by returned value when it's not needed anymore.

Parameters

object Object to be represented as a human readable string.

Returns: String description.

Examples:: error-backtrace.c, libdispatch.c, pack-unpack.c, query.c, shm-client.c, and validation.c.

◆ rpc_data_create()

_Nonnull rpc_object_t rpc_data_create	(	const void *_Nullable	bytes,
		size_t	length,
		_Nullable rpc_binary_destructor_t	destructor
	)

Creates an RPC object holding a binary data.

Parameters

bytes	Pointer to data buffer (void pointer).
length	Length of the data buffer.
destructor	Block to call once reference count drops to 0 (or NULL)

Returns: Newly created object.

◆ rpc_data_create_iov()

_Nonnull rpc_object_t rpc_data_create_iov	(	struct iovec *_Nonnull	iov,
		size_t	niov
	)

The same as rpc_data_create, but takes iovec list as an argument and copies it into a new continuous data buffer.

Parameters

iov	List of iovec to be copied.
niov	Number of iovec in the iovec list.

Returns: Newly created object.

◆ rpc_data_get_bytes()

size_t rpc_data_get_bytes	(	_Nonnull rpc_object_t	xdata,
		void *_Nonnull	buffer,
		size_t	off,
		size_t	length
	)

Creates a copy of a slice of a internal data buffer of a provided object.

Parameters

xdata	Input object.
buffer	Output buffer.
off	Start offset for the copy operation.
length	Requested size of a copy.

Returns: Size of a copied data.

◆ rpc_data_get_bytes_ptr()

const void* _Nullable rpc_data_get_bytes_ptr ( _Nonnull rpc_object_t xdata )

Returns the pointer to internal binary data buffer of a provided object.

Parameters

xdata Input object

Returns: Pointer to an object's data buffer (void pointer).

◆ rpc_data_get_length()

size_t rpc_data_get_length ( _Nonnull rpc_object_t xdata )

Returns the length of internal binary data buffer of a provided object.

Parameters

xdata Input object

Returns: Size of an object's data buffer.

◆ rpc_date_create()

_Nonnull rpc_object_t rpc_date_create ( int64_t interval )

Creates an RPC object holding a date.

Parameters

interval Value of the object (signed 64-bit integer).

Returns: Newly created object.

◆ rpc_date_create_from_current()

_Nonnull rpc_object_t rpc_date_create_from_current ( void )

Creates an RPC object holding a date from current UTC time.

Returns: Newly created object.

◆ rpc_date_get_value()

int64_t rpc_date_get_value ( _Nonnull rpc_object_t xdate )

Returns an integer value of an object (UNIX timestamp).

If rpc_object_t passed as the first argument if not of RPC_TYPE_DATE type, the function returns 0.

Parameters

xdate Object to read the value from.

Returns: Integer UNIX timestamp value of the object.

◆ rpc_dictionary_apply()

bool rpc_dictionary_apply	(	_Nonnull rpc_object_t	dictionary,
		_Nonnull rpc_dictionary_applier_t	applier
	)

Iterates over a given dictionary. For each of elements executes an applier block, providing a current key and a current value as an applier block's arguments.

If an applier returns false, iteration is terminated and the function returns true (terminated). Otherwise the function iterates to the end of an input array and returns false (finished).

Parameters

dictionary	Input dictionary.
applier	Block to be executed for each of an dictionary's elements.

Returns: Iteration terminated (true)/finished (false) boolean flag.

◆ rpc_dictionary_create()

_Nonnull rpc_object_t rpc_dictionary_create ( void )

Creates a new, empty dictionary of objects.

Returns: Empty dictionary.

◆ rpc_dictionary_create_ex()

_Nonnull rpc_object_t rpc_dictionary_create_ex	(	const char const _Nonnull _Nullable	keys,
		const _Nonnull rpc_object_t *_Nullable	values,
		size_t	count,
		bool	steal
	)

Creates a new dictionary of objects, optionally populating it with data.

Parameters

keys	Array of keys associated with values to insert.
values	Array of objects to insert.
count	Number of items in values.
steal	Reference vs. reference and increment refcount of elements in values.

Returns: Newly created object.

Examples:: pack-unpack.c.

◆ rpc_dictionary_detach_key()

_Nullable rpc_object_t rpc_dictionary_detach_key	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key
	)

Removes a key from dictionary and returns it.

Parameters

dictionary	Input dictionary
key	Key to be detached

Returns: Detached object

◆ rpc_dictionary_dup_fd()

int rpc_dictionary_dup_fd	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key
	)

Duplicates a file descriptor from a given key of an input dictionary.

If a selected key does not exist, or object being held at a given key has a type different from expected (RPC_TYPE_FD), then the function returns 0.

Parameters

dictionary	Input dictionary.
key	File descriptor's key.

Returns: Duplicated file descriptor (integer).

◆ rpc_dictionary_get_bool()

bool rpc_dictionary_get_bool	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key
	)

Returns a value from a given key of an input dictionary.

If a selected key does not exist, or object being held at a given key has a type different from expected (RPC_TYPE_BOOL), then the function returns false.

Parameters

dictionary	Input dictionary.
key	Key storing an output value.

Returns: Boolean value.

◆ rpc_dictionary_get_count()

size_t rpc_dictionary_get_count ( _Nonnull rpc_object_t dictionary )

Returns a number of elements in a provided dictionary.

Parameters

dictionary Input dictionary.

Returns: Number of elements held by an input dictionary.

◆ rpc_dictionary_get_data()

const void* _Nullable rpc_dictionary_get_data	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key,
		size_t *_Nullable	length
	)

Returns a value from a given key of an input dictionary.

If a selected key does not exist, or object being held at a given key has a type different from expected (RPC_TYPE_BINARY), then the function returns NULL.

Parameters

dictionary	Input dictionary.
key	Output value's key.
length	Size of an output buffer.

Returns: Binary output buffer pointer.

◆ rpc_dictionary_get_date()

int64_t rpc_dictionary_get_date	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key
	)

Returns a value from a given key of an input dictionary.

If a selected key does not exist, or object being held at a given key has a type different from expected (RPC_TYPE_DATE), then the function returns 0.

Parameters

dictionary	Input dictionary.
key	Key storing an output value.

Returns: Integer representing a UNIX timestamp.

◆ rpc_dictionary_get_double()

double rpc_dictionary_get_double	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key
	)

Returns a value from a given key of an input dictionary.

If a selected key does not exist, or object being held at a given key has a type different from expected (RPC_TYPE_DOUBLE), then the function returns 0.

Parameters

dictionary	Input dictionary.
key	Key storing an output value.

Returns: Double value.

◆ rpc_dictionary_get_fd()

int rpc_dictionary_get_fd	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key
	)

Returns a value from a given key of an input dictionary.

If a selected key does not exist, or object being held at a given key has a type different from expected (RPC_TYPE_FD), then the function returns 0.

Parameters

dictionary	Input dictionary.
key	Key storing an output value.

Returns: File descriptor value (integer).

◆ rpc_dictionary_get_int64()

int64_t rpc_dictionary_get_int64	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key
	)

Returns a value from a given key of an input dictionary.

If a selected key does not exist, or object being held at a given key has a type different from expected (RPC_TYPE_INT64), then the function returns 0.

Parameters

dictionary	Input dictionary.
key	Key storing an output value.

Returns: 64-bit signed integer value.

◆ rpc_dictionary_get_string()

const char* _Nullable rpc_dictionary_get_string	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key
	)

Returns a value from a given key of an input dictionary.

If a selected key does not exist, or object being held at a given key has a type different from expected (RPC_TYPE_STRING), then the function returns NULL.

Parameters

dictionary	Input dictionary.
key	Key storing an output value.

Returns: String value.

◆ rpc_dictionary_get_uint64()

uint64_t rpc_dictionary_get_uint64	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key
	)

Returns a value from a given key of an input dictionary.

If a selected key does not exist, or object being held at a given key has a type different from expected (RPC_TYPE_UINT64), then the function returns 0.

Parameters

dictionary	Input dictionary.
key	Key storing an output value.

Returns: 64-bit unsigned integer value.

◆ rpc_dictionary_get_value()

_Nullable rpc_object_t rpc_dictionary_get_value	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key
	)

Returns an object held by a provided dictionary at a given key.

If a given key does not exist, then the function returns NULL.

Parameters

dictionary	Input dictionary.
key	Key of an object to be returned.

Returns: Object at a given key.

◆ rpc_dictionary_has_key()

bool rpc_dictionary_has_key	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key
	)

Checks if an input dictionary does have a given key set.

Parameters

dictionary	Input dictionary.
key	Key to be tested.

Returns: Boolean check result.

◆ rpc_dictionary_map()

void rpc_dictionary_map	(	_Nonnull rpc_object_t	dictionary,
		_Nonnull rpc_dictionary_mapper_t	mapper
	)

Parameters

dictionary
mapper

◆ rpc_dictionary_remove_all()

void rpc_dictionary_remove_all ( _Nonnull rpc_object_t dictionary )

Removes all keys and their associated values from a dictionary.

Parameters

dictionary Input dictionary.

◆ rpc_dictionary_remove_key()

void rpc_dictionary_remove_key	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key
	)

Removes an object from a given key of a provided dictionary.

Parameters

dictionary	Input dictionary.
key	Key to be removed.

◆ rpc_dictionary_set_bool()

void rpc_dictionary_set_bool	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key,
		bool	value
	)

Sets a selected key of an input dictionary to a newly created RPC object holding a given boolean value.

Parameters

dictionary	Input dictionary.
key	Key to store an input value.
value	Input value (boolean).

◆ rpc_dictionary_set_data()

void rpc_dictionary_set_data	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key,
		const void *_Nonnull	value,
		size_t	length
	)

Sets a selected key of an input dictionary to a newly created RPC object holding a given binary data of a specified length.

Parameters

dictionary	Input dictionary.
key	Key to store an input value.
value	Input binary data buffer.
length	Size of an input data buffer.

◆ rpc_dictionary_set_date()

void rpc_dictionary_set_date	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key,
		int64_t	value
	)

Sets a selected key of an input dictionary to a newly created RPC object holding a given UNIX timestamp value represented as an integer.

Parameters

dictionary	Input dictionary.
key	Key to store an input value.
value	Input value (UNIX timestamp represented as an integer).

◆ rpc_dictionary_set_double()

void rpc_dictionary_set_double	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key,
		double	value
	)

Sets a selected key of an input dictionary to a newly created RPC object holding a given double value.

Parameters

dictionary	Input dictionary.
key	Key to store an input value.
value	Input value (double).

◆ rpc_dictionary_set_fd()

void rpc_dictionary_set_fd	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key,
		int	value
	)

Sets a selected key of an input dictionary to a newly created RPC object holding a given file descriptor value.

Parameters

dictionary	Input dictionary.
key	Key to store an input value.
value	Input file descriptor (integer).

◆ rpc_dictionary_set_int64()

void rpc_dictionary_set_int64	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key,
		int64_t	value
	)

Sets a selected key of an input dictionary to a newly created RPC object holding a given 64-bit signed integer value.

Parameters

dictionary	Input dictionary.
key	Key to store an input value.
value	Input value (64-bit signed integer).

◆ rpc_dictionary_set_string()

void rpc_dictionary_set_string	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key,
		const char *_Nonnull	value
	)

Sets a selected key of an input dictionary to a newly created RPC object holding a given string value.

Parameters

dictionary	Input dictionary.
key	Key to store an input value.
value	Input string (null byte terminated constant character pointer).

◆ rpc_dictionary_set_uint64()

void rpc_dictionary_set_uint64	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key,
		uint64_t	value
	)

Sets a selected key of an input dictionary to a newly created RPC object holding a given 64-bit unsigned integer value.

Parameters

dictionary	Input dictionary.
key	Key to store an input value.
value	Input value (64-bit unsigned integer).

◆ rpc_dictionary_set_value()

void rpc_dictionary_set_value	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key,
		_Nonnull rpc_object_t	value
	)

Inserts an object to an input dictionary at a given key and increments object's refcount.

If a key is already occupied, then a new object takes place of an old object and the refcount of an old object is decremented.

If an object is NULL, then this function removes an old object stored at a given key.

Parameters

dictionary	Input dictionary.
key	Key to store a value.
value	Value to be inserted.

◆ rpc_dictionary_steal_value()

void rpc_dictionary_steal_value	(	_Nonnull rpc_object_t	dictionary,
		const char *_Nonnull	key,
		rpc_object_t _Nonnull	value
	)

Inserts an object to an input dictionary at a given key.

If a key is already occupied, then a new object takes place of an old object and the refcount of an old object is decremented.

If an object is NULL, then this function removes an old object stored at a given key.

Parameters

dictionary	Input dictionary.
key	Key to store a value.
value	Value to be inserted.

◆ rpc_double_create()

_Nonnull rpc_object_t rpc_double_create ( double value )

Creates an RPC object holding a double value.

Parameters

value Value of the object (double).

Returns: Newly created object.

◆ rpc_double_get_value()

double rpc_double_get_value ( _Nonnull rpc_object_t xdouble )

Returns a double value of an object.

If rpc_object_t passed as the first argument if not of RPC_TYPE_DOUBLE type, the function returns 0.

Parameters

xdouble Object to read the value from.

Returns: Double value of the object.

◆ rpc_equal()

bool rpc_equal	(	_Nullable rpc_object_t	o1,
		_Nullable rpc_object_t	o2
	)

Compares objects provided as the function arguments and returns true if they are equivalent, otherwise returns false.

Parameters

o1	Object to be compared.
o2	Object to be compared.

Returns: Comparison result.

◆ rpc_error_create()

_Nonnull rpc_object_t rpc_error_create	(	int	code,
		const char *_Nonnull	msg,
		_Nullable rpc_object_t	extra
	)

Creates an RPC object representing an error condition with automatically extracted stack trace.

It can hold data about numerical error code, string describing the actual error in human readable format and extra auxiliary data.

Extra is an optional argument and can be safely set to NULL when not needed.

Parameters

code	Numerical error code.
msg	String representing an actual error description.
extra	Extra data (optional).

Returns: Newly created object.

Examples:: error-backtrace.c.

◆ rpc_error_create_with_stack()

_Nonnull rpc_object_t rpc_error_create_with_stack	(	int	code,
		const char *_Nonnull	msg,
		_Nullable rpc_object_t	extra,
		_Nullable rpc_object_t	stack
	)

Creates an RPC object representing an error condition with externally provided extracted stack trace.

It can hold data about numerical error code, string describing the actual error in human readable format and extra auxiliary data.

Extra is an optional argument and can be safely set to NULL when not needed.

Parameters

code	Numerical error code.
msg	String representing an actual error description.
extra	Extra data (optional).
stack	Externally provided stack trace of an error.

Returns: Newly created object.

◆ rpc_error_get_code()

int rpc_error_get_code ( _Nonnull rpc_object_t error )

Returns numerical error code of a provided error object.

Parameters

error Input error object.

Returns: Numerical error code.

◆ rpc_error_get_extra()

_Nullable rpc_object_t rpc_error_get_extra ( _Nonnull rpc_object_t error )

Returns an extra (auxiliary data) set during creation of a provided provided error object.

Parameters

error Input error object.

Returns: Extra data attached to an error.

◆ rpc_error_get_message()

const char* _Nullable rpc_error_get_message ( _Nonnull rpc_object_t error )

Returns string description of a provided error object.

Parameters

error Input error object.

Returns: String description of an error condition.

Examples:: client.c, and server.c.

◆ rpc_error_get_stack()

_Nullable rpc_object_t rpc_error_get_stack ( _Nonnull rpc_object_t error )

Returns a stack trace associated with an error condition of a provided error object.

Parameters

error Input error object.

Returns: Stack trace of an error.

◆ rpc_error_set_extra()

void rpc_error_set_extra	(	_Nonnull rpc_object_t	error,
		_Nonnull rpc_object_t	extra
	)

Sets an extra data attached to an error.

Parameters

error	Input error object.
extra	Extra data to be attached to an error.

◆ rpc_fd_create()

_Nonnull rpc_object_t rpc_fd_create ( int fd )

Creates an RPC object holding a file descriptor.

Parameters

fd	Value of the object (signed integer).

Returns: Newly created object.

Examples:: fd-client.c, and log-reader.c.

◆ rpc_fd_dup()

int rpc_fd_dup ( _Nonnull rpc_object_t xfd )

Creates a duplicate of a file descriptor held by a provided object.

Parameters

xfd	Input object.

Returns: Newly created file descriptor.

◆ rpc_fd_get_value()

int rpc_fd_get_value ( _Nonnull rpc_object_t xfd )

Returns a value of a file descriptor helf by a provided object.

Parameters

xfd	Input object.

Returns: File descriptor's value.

◆ rpc_get_column_number()

size_t rpc_get_column_number ( _Nonnull rpc_object_t object )

Gets column number of object location in source file (if any).

If the object was read from a file using RPC serializer API, this function might return a column number where the object was located in the source file. Otherwise, it returns 0.

Parameters

object Object to get column number from

Returns: A column number in source file or 0

◆ rpc_get_last_error()

_Nullable rpc_object_t rpc_get_last_error ( void )

Returns last runtime error reported by the library.

Returns: Error object.

Examples:: client.c, and server.c.

◆ rpc_get_line_number()

size_t rpc_get_line_number ( _Nonnull rpc_object_t object )

Gets line number of object location in source file (if any).

If the object was read from a file using RPC serializer API, this function might return a line number where the object was located in the source file. Otherwise, it returns 0.

Parameters

object Object to get line number from

Returns: A line number in source file or 0

◆ rpc_get_refcount()

int rpc_get_refcount ( _Nullable rpc_object_t object )

Returns reference count of an object.

This function shall be usd only for debugging purposes.

Parameters

object Object to read reference count from

Returns: Reference count

◆ rpc_get_type()

rpc_type_t rpc_get_type ( _Nonnull rpc_object_t object )

Returns the type of an object.

Parameters

object Input object.

Returns: Object's type.

◆ rpc_get_type_name()

const char* _Nullable rpc_get_type_name ( rpc_type_t type )

Returns the string name of a type.

Parameters

type Type

Returns: Type name

◆ rpc_hash()

size_t rpc_hash ( _Nonnull rpc_object_t object )

Returns numerical hash calculated from the value of an object.

Parameters

object Object to be hashed.

Returns: Numerical hash.

◆ rpc_int64_create()

_Nonnull rpc_object_t rpc_int64_create ( int64_t value )

Creates an object holding a signed 64-bit integer value.

Parameters

value Value of the object (signed 64-bit integer).

Returns: Newly created object.

Examples:: pack-unpack.c, query.c, and server.c.

◆ rpc_int64_get_value()

int64_t rpc_int64_get_value ( _Nonnull rpc_object_t xint )

Returns an integer value of an object.

If rpc_object_t passed as the first argument if not of RPC_TYPE_INT64 type, the function returns -1.

Parameters

xint	Object to read the value from.

Returns: Integer value of the object.

◆ rpc_null_create()

_Nonnull rpc_object_t rpc_null_create ( void )

Creates an object holding null value.

Returns: newly created object

Examples:: server.c.

◆ rpc_object_pack()

_Nullable rpc_object_t rpc_object_pack	(	const char *_Nonnull	fmt,
			...
	)

Packs provided values accordingly to a specified format string an into object compatible with library's data model.

Each set of characters of the format string represents a single creation step of an output object and may require from 0 to n arguments. Character sets are separated with ',' character.

Example: [s,s,s] represents an array containing three strings and require three char * arguments to be passed to the function after the format string. Example: {i,i,i} represents a dictionary containing three integers and require three pairs of (char *, int) arguments to be passed to the function after the format string. First of each two is representing a dictionary key, which is always a char * and second an actual integer value to be packed.

The syntax above allows easy pack of dictionaries containing dynamically generated keys and continuous arrays. There is also second format string syntax, especially handy when packing dictionaries with statically known keys and noncontinuous arrays. That syntax allows specifying array indexes and name of dictionary keys directly in the format string and separating them from the value type character with ':' character.

Example: [0:s,1:s,20:s] represents an array containing three strings and require three char * arguments to be passed to the function after the format string. Gap between index 1 and 20 is going to be filled with NULL RPC objects. Example: {example_key:i,other_key:i,yet_another_key:i} represents a dictionary containing three integers and require three int arguments to be passed to the function after the format string.

Both syntaxes are allowed to be mixed together in a single format string creating complex data structures representations. Each explicitly specified array index is resetting an internal state of the pack function, so mixing explicit and implicit indexing syntax within a single array is going to result in a following behavior:

Implicit indexing always starts from the index 0
Next implicit index is always created by incrementing an index used in previous value (either implicit or explicit).
Explicit indexing can either create a padding with NULL RPC objects within the array if the index is bigger than the current array length, or overwrite already packed values if index is smaller than the current array length.
Explicit array indexing does not have to be represented in a growing order, or any sorted order

Example: {[i,s,i],[10:b,s,1:d,u],{key:v,f,u}} Array in the middle of the example below is going to be created in the following order: indexes 0-9 are going to be padded with the NULL RPC objects, index 10 is going to contain BOOL RPC object, index 11 is going to contain a STRING RPC object, function jumps back to the index 1 and replaces NULL RPC object with the DOUBLE RPC object, function increments last index, that results in the index 2 and replaces the NULL RPC object below that index with UNSIGNED INT RPC object.

Format string can also contain single quoted inline strings for ease of packing of constant values.

Example: {inline_string:'inline_string_value'}

Format string syntax:

v - librpc object - args: rpc_object_t object
V - librpc object (increases refcount) - args: rpc_object_t object
n - Null object
b - Boolean object - args: bool value
B - Binary object - args: void *buffer, size_t size, bool copy
I - Binary object (from list of iovec) - args: struct iovec *list, size_t list_size
f - File descriptor object - args: int fd
i - Integer object - args: int value
u - Unsigned integer object - args: unsigned int value
d - Double object - args: double value
D - Date object - args: int interval
s - String object - args: char *string
' - Inline string start/end = args: takes no arguments
{ - Open dictionary - values inside of dictionary require additional char *key argument at the beginning of their usual argument list
} - Close dictionary
[ - Open array
] - Close array

Parameters

fmt	Format string.
...	Variable length list of values to be packed.

Returns: Packed object.

Examples:: libdispatch.c, pack-unpack.c, query.c, and server.c.

◆ rpc_object_unpack()

int rpc_object_unpack	(	_Nonnull	rpc_object_t,
		const char *_Nonnull	fmt,
			...
	)

Unpacks provided values accordingly to a specified format string from an object.

Each character set of the format string represents a single unpack step and may require from 0 to n arguments. Character sets are separated with ',' character.

Example: [s,s,s] represents an array containing three strings and require three char ** arguments to be passed to the function after the format string. Example: {i,i,i} represents a dictionary containing three integers and require three pairs of (char *, int *) arguments to be passed to the function after the format string. First of each two is representing a dictionary key, which is always a char * and second an actual integer value to be unpacked.

The syntax above allows easy unpack of dictionaries containing dynamically generated keys and continuous arrays. There is also second format string syntax, especially handy when unpacking dictionaries with statically known keys and noncontinuous reads from arrays. That syntax allows specifying array indexes and name of dictionary keys directly in the format string and separating them from the value type character with ':' character.

Example: [0:s,1:s,20:s] represents an array containing three strings and require three char ** arguments to be passed to the function after the format string. Example: {example_key:i,other_key:i,yet_another_key:i} represents a dictionary containing three integers and require three int * arguments to be passed to the function after the format string.

Both syntaxes are allowed to be mixed together in a single format string creating complex data structures representations. Each explicitly specified array index is resetting an internal state of the unpack function, so mixing explicit and implicit indexing syntax within a single array is going to result in a following behavior:

Implicit indexing always starts from the index 0
Next implicit index is always created by incrementing an index used in previous value (either implicit or explicit).
Explicit array indexing does not have to be represented in a growing order, or any sorted order

Example: {[i,s,i],[10:b,s,1:d,u],{key:v,f,u}}

The function returns the number of successfully processed format characters (excluding '{', '[', ']', '}'), or an error as a negative value.

Format string syntax:

* - Array's no-op - skip index
v - Object - args: rpc_object_t *object
b - Boolean object - args: bool *value
f - File descriptor object - args: int *fd
i - Integer object - args: int *value
u - Unsigned integer object - args: unsigned int *value
d - Double object - args: double *value
s - String object - args: char **string
R - Rest of array - returns the rest of an array into separate object - args: rpc_object_t *object
{ - Open dictionary - values inside of dictionary require additional char *key argument at the beginning of their usual argument list
} - Close dictionary
[ - Open array
] - Close array

Parameters

fmt	Format string.
...	Variable length list of values to be unpacked.

Returns: The number of successfully unpacked objects or -1 on error.

Examples:: client.c, fd-server.c, pack-unpack.c, and shm-server.c.

◆ rpc_object_vpack()

_Nullable rpc_object_t rpc_object_vpack	(	const char *_Nonnull	fmt,
		va_list	ap
	)

Packs provided values accordingly to a specified format string an into object compatible with library's data model.

The functions acts exactly the same as the rpc_object_pack function, but takes assembled variable arguments list structure as its argument.

Parameters

fmt	Format string.
ap	Variable arguments list structure.

Returns: Packed object.

◆ rpc_object_vunpack()

int rpc_object_vunpack	(	_Nonnull	rpc_object_t,
		const char *_Nonnull	fmt,
		va_list	ap
	)

Unpacks provided values accordingly to a specified format string from an object.

The functions acts exactly the same as the rpc_object_unpack function, but takes assembled variable arguments list structure as its argument.

Parameters

fmt	Format string.
ap	Variable arguments list structure.

Returns: Unpacking status. Errors are reported as negative values.

◆ rpc_release_impl()

int rpc_release_impl ( _Nonnull rpc_object_t object )

Decrements reference count of an object.

Function returns reference count of an object after operation.

Parameters

object Object to decrement reference count of.

Returns: Reference count after operation.

◆ rpc_retain()

_Nonnull rpc_object_t rpc_retain ( _Nonnull rpc_object_t object )

Increments reference count of an object.

For convenience, the function returns reference to an object passed as the first argument.

Parameters

object Object to increment reference count of.

Returns: Same object

◆ rpc_string_create()

_Nonnull rpc_object_t rpc_string_create ( const char *_Nonnull string )

Creates an RPC object holding a string.

Parameters

string Value of the object (constant character pointer).

Returns: Newly created object.

Examples:: fd-transport.c, loopback.c, server.c, and validation.c.

◆ rpc_string_create_len()

_Nonnull rpc_object_t rpc_string_create_len	(	const char *_Nonnull	string,
		size_t	length
	)

Creates an RPC object holding a string of a specified length.

Parameters

string	Value of the object (constant character pointer).
length	Length of an input string.

Returns: Newly created object.

◆ rpc_string_create_with_format()

_Nonnull rpc_object_t rpc_string_create_with_format	(	const char *_Nonnull	fmt,
			...
	)

Creates an RPC object holding a string formatted using the regular printf function format string and arguments.

Parameters

fmt	Format string.
...	Variable length list of input data arguments for formatting.

Returns: Newly created object.

Examples:: server.c.

◆ rpc_string_create_with_format_and_arguments()

_Nonnull rpc_object_t rpc_string_create_with_format_and_arguments	(	const char *_Nonnull	fmt,
		va_list	ap
	)

Creates an RPC object holding a string formatted using the regular printf function format string and arguments (as variable arguments list type).

Parameters

fmt	Format string.
ap	Variable arguments list.

Returns: Newly created object.

◆ rpc_string_get_length()

size_t rpc_string_get_length ( _Nonnull rpc_object_t xstring )

Returns the length of internal string buffer of a provided object.

Parameters

xstring Input object

Returns: Size of an object's data buffer.

◆ rpc_string_get_string_ptr()

const char* _Nullable rpc_string_get_string_ptr ( _Nonnull rpc_object_t xstring )

Returns the pointer to internal string data buffer of a provided object.

Parameters

xstring Input object

Returns: Pointer to an object's data buffer (constant character pointer).

Examples:: client.c, fd-client.c, fd-transport.c, and loopback.c.

◆ rpc_uint64_create()

_Nonnull rpc_object_t rpc_uint64_create ( uint64_t value )

Creates an RPC object holding an unsigned 64-bit integer value.

Parameters

value Value of the object (unsigned 64-bit integer).

Returns: Newly created object.

◆ rpc_uint64_get_value()

uint64_t rpc_uint64_get_value ( _Nonnull rpc_object_t xuint )

Returns an integer value of an object.

If rpc_object_t passed as the first argument if not of RPC_TYPE_UINT64 type, the function returns 0.

Parameters

xuint Object to read the value from.

Returns: Integer value of the object.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ RPC_ARRAY_APPLIER

◆ RPC_ARRAY_CMP

◆ rpc_auto_object_t

◆ RPC_BINARY_DESTRUCTOR

◆ RPC_BINARY_DESTRUCTOR_ARG

◆ RPC_DICTIONARY_APPLIER

◆ rpc_is_error

◆ rpc_release

◆ rpc_swap

Typedef Documentation

◆ rpc_array_applier_t

◆ rpc_array_cmp_t

◆ rpc_binary_destructor_t

◆ rpc_dictionary_applier_t

◆ rpc_object_t

Enumeration Type Documentation

◆ rpc_type_t

Function Documentation

◆ rpc_array_append_stolen_value()

◆ rpc_array_append_value()

◆ rpc_array_apply()

◆ rpc_array_contains()

◆ rpc_array_create()

◆ rpc_array_create_ex()

◆ rpc_array_dup_fd()

◆ rpc_array_get_bool()

◆ rpc_array_get_count()

◆ rpc_array_get_data()

◆ rpc_array_get_date()

◆ rpc_array_get_double()

◆ rpc_array_get_fd()

◆ rpc_array_get_int64()

◆ rpc_array_get_string()

◆ rpc_array_get_uint64()

◆ rpc_array_get_value()

◆ rpc_array_map()

◆ rpc_array_remove_all()

◆ rpc_array_remove_index()

◆ rpc_array_reverse_apply()

◆ rpc_array_set_bool()

◆ rpc_array_set_data()

◆ rpc_array_set_date()

◆ rpc_array_set_double()

◆ rpc_array_set_fd()

◆ rpc_array_set_int64()

◆ rpc_array_set_string()

◆ rpc_array_set_uint64()

◆ rpc_array_set_value()

◆ rpc_array_slice()

◆ rpc_array_sort()

◆ rpc_array_steal_value()

◆ rpc_bool_create()

◆ rpc_bool_get_value()

◆ rpc_cmp()

◆ rpc_copy()

◆ rpc_copy_description()

◆ rpc_data_create()

◆ rpc_data_create_iov()

◆ rpc_data_get_bytes()

◆ rpc_data_get_bytes_ptr()

◆ rpc_data_get_length()

◆ rpc_date_create()

◆ rpc_date_create_from_current()

◆ rpc_date_get_value()

◆ rpc_dictionary_apply()

◆ rpc_dictionary_create()

◆ rpc_dictionary_create_ex()

◆ rpc_dictionary_detach_key()

◆ rpc_dictionary_dup_fd()

◆ rpc_dictionary_get_bool()

◆ rpc_dictionary_get_count()

◆ rpc_dictionary_get_data()

◆ rpc_dictionary_get_date()

◆ rpc_dictionary_get_double()