# Overview

VSOA C environment extension library. Includes Timer, Client Robot, Parallel RPC Listener and Speed Regulator.

# Support

The following shows vsoa extension library APIs.

# VSOA Timer

VSOA timer is a convenient timer module, developers can easily implement various timing functions.

Use following API to initialize the VSOA timer library:

bool vsoa_timer_init(void);

• Returns: Whether the initialization is successful.

NOTICE: The initialization function must first be called.

Use following API to create a VSOA timer:

vsoa_timer_t *vsoa_timer_create(void);

• Returns: If success, return the timer object, return NULL if any errors.

Use following API to delete VSOA timer:

void vsoa_timer_delete(vsoa_timer_t *timer);

Whether the timer is working or not, it can be deleted.

Use following API to start VSOA timer:

// The time unit is nanoseconds
bool vsoa_timer_start(vsoa_timer_t *timer, int64_t count, int64_t interval, vsoa_timer_ontime_func_t callback, void *arg);

// The time unit is millisecond
bool vsoa_timer_start_ms(vsoa_timer_t *timer, int64_t count, int64_t interval, vsoa_timer_ontime_func_t callback, void *arg);

• count First timer timeout.
• interval Periodic interval.
• callback Timer expiration callback.
• arg Timer expiration callback argument.
• Returns: Is the startup successful?

When starting a running timer, the system automatically stops the timer and starts the timer with new parameters.

The timer expiration callback function type is as follows:

typedef void (*vsoa_timer_ontime_func_t)(void *arg, vsoa_timer_t *timer);

NOTICE: The callback function will be called in the timer service thread context.

Use following API to stop VSOA timer:

void vsoa_timer_stop(vsoa_timer_t *timer);

Use following API to determine whether VSOA timer is running:

bool vsoa_timer_is_started(vsoa_timer_t *timer);

• Returns: Whether VSOA timer is running.

Each timer object can set user-custom data structure

Use the following functions to set and get user-custom data:

// Set user-custom data
void vsoa_timer_set_custom(vsoa_timer_t *timer, void *custom);

// Get user-custom data
void *vsoa_timer_custom(vsoa_timer_t *timer);

# VSOA Client Auto Robot

The C environment VSOA client library provides basic client operation API, but it is not very convenient to use. Developers need to handle the network connection and event loop by themselves. The Client Auto Robot module provides the ability to automatically process network connections. Developers only need to care about business processing.

Use following API to create a VSOA client auto robot:

vsoa_client_auto_t *vsoa_client_auto_create(vsoa_client_msg_func_t onmsg, void *arg);

• onmsg Subscription callback, this is called after the client receives the subscribed message.
• arg The callback argument.
• Returns: If success, return the client auto object, return NULL if any errors.

The onmsg protype:

typedef void (*vsoa_client_msg_func_t)(void *arg, vsoa_client_t *client, vsoa_url_t *url, vsoa_payload_t *payload, bool quick);

• arg The callback argument.
• client Client object.
• url The URL of this message.
• payload Payload of the URL.
• quick Is it a quick publish message.

For more details, please refer to the vsoa_client_create function.

Use following API to delete VSOA client auto robot:

void vsoa_client_auto_delete(vsoa_client_auto_t *cliauto);

Client auto robot can be deleted regardless of the state of the network connection.

NOTICE: Except vsoa_client_auto_handle other client auto robot functions are not allowed to be called in this client event loop thread context is not allowed to be called in the client event loop, such as asynchronous RPC callback, or subscription message callback, etc.

Use following API to set the connection state change callback of VSOA client auto robot:

bool vsoa_client_auto_setup(vsoa_client_auto_t *cliauto, vsoa_client_conn_func_t onconn, void *arg);

• onconn Connection state change callback.
• arg The callback argument.
• Returns: Whether the operation was successful.

The onconn protype:

typedef void (*vsoa_client_conn_func_t)(void *arg, vsoa_client_auto_t *cliauto, bool connect, const char *info);

• arg The callback argument.
• connect If true means the connection is successful, false means the connection is disconnected.
• info When the connection is successful, it is the server information, and when the connection is disconnected, it is NULL.

When the connection is successful, the robot will immediately subscribe to the subscription URL set set at start, then call the onconn function, and then perform data consistency operations.

If we need robots to automatically synchronize server data maintain data consistency, we can use the following function:

bool vsoa_client_auto_consistent(vsoa_client_auto_t *cliauto, char *const urls[], int url_cnt, unsigned int rpc_timeout);

• urls A collection of URLs that need to be obtained data using RPC GET when the connection is successful.
• url_cnt Number of URLs in the collection.
• rpc_timeout RPC GET timeout, in milliseconds, the minimum is 20ms.
• Returns: Whether the setting was successful.

When VSOA disconnected and reconnected, the server data changes, which we cannot detect, so this function can set the URL collection of interest. The robot will use the RPC call with GET method to continuously obtain these data, and then simulate the server PUBLISH operation. Update the corresponding data The urls specified by this function will be RPC called when the connection is successful.

This function only needs to be set once. After each successful connection, the robot will automatically perform data consistency operations.

NOTICE:

1. Ensure that the data published by the server on the same URL is consistent with the RPC GET data.
2. Rapidly updated publish data should not use this method.
3. This function must be called before vsoa_client_auto_start().

When there is an RPC call pending, and if there is data packet loss, and the client and server need to do their best to perform TCP fast retransmission at this time, you can set this turbo parameter, the minimum value is 25ms. 0 means disable turbo ping.

bool vsoa_client_auto_ping_turbo(vsoa_client_auto_t *cliauto, unsigned int turbo, unsigned int max_cnt);

When turbo ping is enabled, the turbo value must be less than or equal to keepalive in vsoa_client_auto_start.

max_cnt: The maximum number of consecutive bursts must be greater than or equal to 3.

Use following API to start VSOA client auto robot:

bool vsoa_client_auto_start(vsoa_client_auto_t *cliauto, const char *server, const char *passwd, char * const urls[], int url_cnt, unsigned int keepalive, unsigned int conn_timeout, unsigned int reconn_delay);

• server Server address, can be vsoa://hostname or vsoa://ip:port.
• passwd Server password. can be NULL.
• urls When the connection is successful, the topic list that needs to be automatically subscribed is a char * array.
• url_cnt Topic array length.
• keepalive How often to send vsoa ping to detect whether the connection is good after the connection is successful, in milliseconds, the minimum is 50ms. ping timeout same as this value.
• conn_timeout Connection timeout, in milliseconds, the minimum is 20ms.
• reconn_delay Retry wait time after disconnection. in millisecond, the minimum is 20ms.
• Returns: Whether the operation was successful.

Once the client auto robot starts, it will create a new event loop thread, then automatically connect to the specified server, then automatically handle the event loop, automatically reconnect when the connection is disconnected, and automatically handle various errors.

If turbo ping is enable, keepalive is recommended to be an integer multiple of turbo.

Use following API to stop VSOA client auto robot:

bool vsoa_client_auto_stop(vsoa_client_auto_t *cliauto);

Use following API to get VSOA client auto robot client object:

vsoa_client_t *vsoa_client_auto_handle(vsoa_client_auto_t *cliauto);

• Returns: VSOA client object.

This handle is only used for communication, and cannot perform state operations such as connection closing, otherwise it will destroy the client auto logic. This client handle is valid after vsoa_client_auto_create and invalid after vsoa_client_auto_delete.

For more information, please refer to the VSOA sample project.

Use following API to get VSOA client auto robot server address:

bool vsoa_client_auto_server_address(vsoa_client_auto_t *cliauto, struct sockaddr *addr, socklen_t *namelen);

This function is recommended to be called in connect callback. namelen needs to have an initial value to specify the memory size of addr.

# VSOA Parallel RPC Listener

If developers need to process RPC requests in parallel, they can implement it by using this module. This module will create a thread pool to receive and process RPC requests in parallel.

Use following API to create thread pool:

vsoa_plistener_t *vsoa_server_plistener_create(int thd_cnt);

• thd_cnt The number of threads, when it exceeds VSOA_SERVER_MAX_RPC_WORKER_THDS, the thread pool will be created with the number of VSOA_SERVER_MAX_RPC_WORKER_THDS.

Generally, one VSOA server only needs to create one thread pool, and even multiple servers can share one thread pool. Thread pool is independent of server module.

Use following API to delete thread pool:

void vsoa_server_plistener_delete(vsoa_plistener_t *plistener);

WARNING: All vsoa_plistener_handler_t of this plistener can no longer be used, please make sure all vsoa_plistener_handler_t has been called vsoa_server_remove_listener.

Use following API to wraps a parallel RPC callback:

vsoa_plistener_handler_t vsoa_server_plistener_handler(vsoa_plistener_t *plistener, bool parallel, int max_queued, vsoa_server_cmd_func_t callback, void *arg);

• parallel If it is true, it means that this callback can be executed in parallel, and if it is false, it means that this callback does not support parallelism. Developers need to handle the callback thread safety that can be executed in parallel mode.
• max_queued Indicates that if there is processing congestion in this command, what is the max queueing length, if the length is exceeded, this command will blocked until worker thread idle. 0 means infinite max queued length.
• callback Raw RPC request callback.
• arg Raw RPC request callback argument.

The return value type is defined as follows:

typedef struct {
    vsoa_server_cmd_func_t callback;
    void *arg;
} vsoa_plistener_handler_t;

• callback Parallel RPC request callback function.
• arg Parallel RPC request callback argument.

If the vsoa_server_plistener_handler call fails, the callback member of the return value is NULL.

The following is a routine for parallel RPC request callbacks:

static void command_echo (...)
{
    vsoa_server_cli_reply(...);
}

int main (...)
{
    vsoa_url_t url = { .url: "/echo". .url_len: 5 };
    vsoa_server_t *s = vsoa_server_create(...);

    // Create RPC request callback thread pool
    vsoa_plistener_t *pl = vsoa_server_plistener_create(2);

    // Install the RPC request callback directly, 
    // this function will be called in the server event loop, 
    // when the RPC callback is executed, the server does not work
    vsoa_server_add_listener(s, &url, command_echo, NULL);

    // Install parallel RPC request callback,
    // this function will be called in the thread pool,
    // when executing RPC callback, server event loop works normally
    vsoa_plistener_handler_t h = vsoa_server_plistener_handler(pl, true, 0, command_echo, NULL);

    // Install parallel RPC request callback handler
    vsoa_server_add_listener(s, &url, h.callback, h.arg);

    ...
}

# VSOA Speed Regulator

In many cases, we need to control the publish frequency. For example, a monitor cannot accept too fast data updates, but the publish data frequency may be very fast. In this case, we need to change the publish frequency. VSOA Speed Regulator can solve this problem. It can be used on the server or on the client.

Create a speed regulator:

vsoa_regulator_t *vsoa_regulator_create(const struct timespec *period);

• period Initial data submit period. cannot be less than 1ms.
• Returns: Speed regulator.

Delete speed regulator:

void vsoa_regulator_delete(vsoa_regulator_t *regulator);

This function will delete all previously added slots and uncommitted data.

Change regulator period:

bool vsoa_regulator_period(vsoa_regulator_t *regulator, const struct timespec *period);

• period New data submit period. cannot be less than 1ms.
• Returns: Whether the operation was successful.

The period cannot be less than 1ms.

Add a slot:

bool vsoa_regulator_slot(vsoa_regulator_t *regulator, const vsoa_url_t *url, vsoa_regulator_func_t ondelay, void *arg, size_t buf_size);

• url Slot URL key.
• ondelay Delayed trigger function.
• arg Function argument.
• buf_size This URL corresponds to the maximum possible length of the payload.
• Returns: Whether the operation was successful.

Create a slot that buffered the payload of the specified URL and calls the ondelay function periodically.

The ondelay function type is as follows:

typedef void (*vsoa_regulator_func_t)(void *arg, vsoa_url_t *url, vsoa_payload_t *payload);

This callback function is executed in the vsoa timer thread context.

NOTICE: In order to ensure data consistency, this function is mutually exclusive with vsoa_regulator_update() and vsoa_regulator_clear() (executed in the regulator mutex lock state). This function needs to ensure fast data processing and return as soon as possible.

Delete the slot specified by url:

bool vsoa_regulator_unslot(vsoa_regulator_t *regulator, const vsoa_url_t *url);

This function will delete the slot specified by url and clear uncommitted data.

Whether it has the slot specified by url:

bool vsoa_regulator_has_slot(vsoa_regulator_t *regulator, const vsoa_url_t *url, size_t *buf_size);

• buf_size You can get the buffer size specified when the slot was created.

Submit data to the slot specified by url:

bool vsoa_regulator_update(vsoa_regulator_t *regulator, const vsoa_url_t *url, const vsoa_payload_t *payload);

example:

// Slow on message
static void slow_onmessage (void *arg, vsoa_url_t *url, vsoa_payload_t *payload)
{
    printf("On -S.L.O.W- message, URL: %.*s payload: %.*s\n",
           (int)url->url_len, url->url, (int)payload->param_len, payload->param);
}

// Fast on message
static void fast_onmessage (void *arg, vsoa_client_t *client, vsoa_url_t *url, vsoa_payload_t *payload, bool quick)
{
    printf("On -F.A.S.T- message, URL: %.*s payload: %.*s\n",
           (int)url->url_len, url->url, (int)payload->param_len, payload->param);

    vsoa_regulator_update(regulator, url, payload);
}

int main (int argc, char **argv)
{
    vsoa_url_t url;
    struct timespec period = { 3, 0 }; // Notify data every 3 seconds.

    regulator = vsoa_regulator_create(&period);
    url.url = ...;
    url.url_len = strlen(url.url);
    vsoa_regulator_slot(regulator, &url, slow_onmessage, NULL, 1024); // Create slot with 1024 bytes buffer.

    cliauto = vsoa_client_auto_create(fast_onmessage, NULL); // Create Client auto robot.
    ...
}

Clear buffered data specified by url:

bool vsoa_regulator_clear(vsoa_regulator_t *regulator, const vsoa_url_t *url);