API Reference#

ucall#

Author

Ash Vardanian

Date

Feb 3, 2023

Defines

UCALL_VERSION_MAJOR#
UCALL_VERSION_MINOR#
UCALL_VERSION_PATCH#

Typedefs

typedef void *ucall_server_t#
typedef void *ucall_call_t#
typedef void *ucall_callback_tag_t#
typedef char const *ucall_str_t#
typedef void (*ucall_callback_t)(ucall_call_t, ucall_callback_tag_t)#
typedef struct ucall_config_t ucall_config_t#

Configuration parameters for ucall_init().

Functions

void ucall_init(ucall_config_t *config, ucall_server_t *server)#

Initializes the server state.

Parameters:

  • config – Input and output argument, that will be updated to export set configuration.

  • server – Output variable, which, on success, will be an initialized server. Don’t forget to free its memory with ucall_free() at the end.

void ucall_free(ucall_server_t)#
void ucall_add_procedure(ucall_server_t server, ucall_str_t name, ucall_callback_t callback, ucall_callback_tag_t callback_tag)#

Registers a function callback to be triggered by the server, when a matching request arrives.

Parameters:

  • server – Must be pre-initialized with ucall_init().

  • name – The string to be matched against “method” in every JSON request.

  • callback – Function pointer to the callback.

  • callback_tag – Optional payload/tag, often pointing to metadata about expected “params”, mostly used for higher-level runtimes, like CPython.

void ucall_take_call(ucall_server_t server, uint16_t thread_idx)#

Perform a single blocking round of polling on the current calling thread.

Parameters:

thread_idx – Assuming that the ::server itself has memory reserves for every thread, the caller must provide a ::thread_idx uniquely identifying current thread with a number from zero to ucall_config_t::max_threads.

void ucall_take_calls(ucall_server_t server, uint16_t thread_idx)#

Blocks current thread, replying to requests in a potentially more efficient way, than just a while loop calling ucall_take_call().

Parameters:

thread_idx – Assuming that the ::server itself has memory reserves for every thread, the caller must provide a ::thread_idx uniquely identifying current thread with a number from zero to ucall_config_t::max_threads.

bool ucall_param_named_bool(ucall_call_t call, ucall_str_t json_pointer, size_t json_pointer_length, bool *output)#
bool ucall_param_named_i64(ucall_call_t call, ucall_str_t json_pointer, size_t json_pointer_length, int64_t *output)#
bool ucall_param_named_f64(ucall_call_t call, ucall_str_t json_pointer, size_t json_pointer_length, double *output)#
bool ucall_param_named_str(ucall_call_t call, ucall_str_t json_pointer, size_t json_pointer_length, ucall_str_t *output, size_t *output_length)#
bool ucall_param_positional_bool(ucall_call_t, size_t, bool*)#
bool ucall_param_positional_i64(ucall_call_t, size_t, int64_t*)#
bool ucall_param_positional_f64(ucall_call_t, size_t, double*)#
bool ucall_param_positional_str(ucall_call_t, size_t, ucall_str_t*, size_t*)#
void ucall_call_reply_content(ucall_call_t call, ucall_str_t json_reply, size_t json_reply_length)#
Parameters:

  • call – Encapsulates the context and the arguments of the current request.

  • json_reply – The response to send, which must be a valid JSON string.

  • json_reply_length – An option length of ::json_reply.

void ucall_call_reply_error(ucall_call_t call, int error_code, ucall_str_t error_message, size_t error_message_length)#
Parameters:

  • call – Encapsulates the context and the arguments of the current request.

  • error_message – An optional string.

  • error_message_length – An option length of ::json_reply.

void ucall_call_reply_error_invalid_params(ucall_call_t)#
void ucall_call_reply_error_out_of_memory(ucall_call_t)#
void ucall_call_reply_error_unknown(ucall_call_t)#
bool ucall_param_named_json(ucall_call_t, ucall_str_t, size_t, ucall_str_t*, size_t*)#
bool ucall_param_positional_json(ucall_call_t, size_t, ucall_str_t*, size_t*)#
struct ucall_config_t
#include <ucall.h>

Configuration parameters for ucall_init().

Public Members

char const *hostname#
uint16_t port#
uint16_t queue_depth#
uint16_t max_callbacks#
uint16_t max_threads#
int32_t logs_file_descriptor#

Common choices, aside from a TCP socket are:

STDOUT_FILENO: console output. STDERR_FILENO: errors.

char const *logs_format#

Can be:

“human” will print human-readable unit-normalized lines. “json” will output newline-delimited JSONs documents.

uint16_t max_batch_size#
uint32_t max_concurrent_connections#
uint32_t max_lifetime_micro_seconds#
uint32_t max_lifetime_exchanges#
bool use_ssl#

Enable SSL.

char const *ssl_private_key_path#

Private Key required for SSL.

char const **ssl_certificates_paths#

At least one certificate is required for SSL.

size_t ssl_certificates_count#

Certificates count.