I/O multiplexers

Overview

This API is dedicated to work with arbitrary I/O multiplexer functions in the single way. More…

// typedefs

typedef enum tapi_iomux_evt tapi_iomux_evt;
typedef struct tapi_iomux_handle tapi_iomux_handle;
typedef struct tapi_iomux_evt_fd tapi_iomux_evt_fd;
typedef void (*tapi_iomux_method_create)(tapi_iomux_handle *iomux);

typedef void (*tapi_iomux_method_add)(
    tapi_iomux_handle *iomux,
    int fd,
    tapi_iomux_evt evt
    );

typedef void (*tapi_iomux_method_mod)(
    tapi_iomux_handle *iomux,
    int fd,
    tapi_iomux_evt evt
    );

typedef void (*tapi_iomux_method_del)(
    tapi_iomux_handle *iomux,
    int fd
    );

typedef int (*tapi_iomux_method_call)(
    tapi_iomux_handle *iomux,
    int timeout,
    tapi_iomux_evt_fd **revts
    );

typedef void (*tapi_iomux_method_destroy)(tapi_iomux_handle *iomux);
typedef struct tapi_iomux_methods tapi_iomux_methods;
typedef struct tapi_iomux_select_context tapi_iomux_select_context;
typedef struct tapi_iomux_poll_context tapi_iomux_poll_context;
typedef struct tapi_iomux_epoll_context tapi_iomux_epoll_context;
typedef struct tapi_iomux_evts_list tapi_iomux_evts_list;
typedef struct tapi_iomux_evts_list_h tapi_iomux_evts_list_h;

// enums

enum tapi_iomux_evt;
enum tapi_iomux_type;

// structs

struct tapi_iomux_epoll_context;
struct tapi_iomux_evt_fd;
struct tapi_iomux_evts_list;
struct tapi_iomux_handle;
struct tapi_iomux_methods;
struct tapi_iomux_poll_context;
struct tapi_iomux_select_context;

// global functions

RPCBITMAP2STR(tapi_iomux_event, IOMUX_EVENT_MAPPING_LIST);
tapi_iomux_type tapi_iomux_call_str2en(const char* iomux);
const char* tapi_iomux_call_en2str(tapi_iomux_type iomux_type);
short int tapi_iomux_evt_to_poll(tapi_iomux_evt iomux_evt_mask);
uint32_t tapi_iomux_evt_to_epoll(tapi_iomux_evt iomux_evt_mask);
tapi_iomux_evt tapi_iomux_poll_to_evt(short int poll_evt_mask);
tapi_iomux_evt tapi_iomux_epoll_to_evt(uint32_t epoll_evt_mask);
SLIST_HEAD(tapi_iomux_evts_list_h, tapi_iomux_evts_list);
tapi_iomux_handle* tapi_iomux_create(rcf_rpc_server* rpcs, tapi_iomux_type type);
void tapi_iomux_add(tapi_iomux_handle* iomux, int fd, tapi_iomux_evt evt);
void tapi_iomux_mod(tapi_iomux_handle* iomux, int fd, tapi_iomux_evt evt);
void tapi_iomux_del(tapi_iomux_handle* iomux, int fd);
void tapi_iomux_set_sigmask(tapi_iomux_handle* iomux, rpc_sigset_p sigmask);
int tapi_iomux_call(tapi_iomux_handle* iomux, int timeout, tapi_iomux_evt_fd** revts);
int tapi_iomux_pcall(tapi_iomux_handle* iomux, int timeout, rpc_sigset_p sigmask, tapi_iomux_evt_fd** revts);
void tapi_iomux_destroy(tapi_iomux_handle* iomux);
tapi_iomux_evt_fd* tapi_iomux_epoll_get_events(tapi_iomux_handle* iomux, struct rpc_epoll_event* events, int evts_num);

// macros

#define BIT_MAP_ENTRY(entry_val_)
#define IOMUX_EVENT_MAPPING_LIST
#define TAPI_IOMUX_MAPPING_LIST
#define TAPI_IOMUX_MAX
#define TAPI_IOMUX_MIN
#define TEST_GET_TE_IOMUX_FUNC(var_name_)

Detailed Documentation

This API is dedicated to work with arbitrary I/O multiplexer functions in the single way.

Typedefs

typedef enum tapi_iomux_evt tapi_iomux_evt

Type of events used in iomux API.

typedef void (*tapi_iomux_method_create)(tapi_iomux_handle *iomux)

Function prototype to create a multiplexer.

Parameters:

iomux

The multiplexer handle.

typedef void (*tapi_iomux_method_add)(
    tapi_iomux_handle *iomux,
    int fd,
    tapi_iomux_evt evt
    )

Function prototype to add a file descriptor to a multiplexer set.

Parameters:

iomux	The multiplexer handle.
fd	The file descriptor to add to the multiplexer set.
evt	Requested events.

typedef void (*tapi_iomux_method_mod)(
    tapi_iomux_handle *iomux,
    int fd,
    tapi_iomux_evt evt
    )

Function prototype to modify a file descriptor events.

Parameters:

iomux	The multiplexer handle.
fd	The file descriptor to modify events for.
evt	New events.

typedef void (*tapi_iomux_method_del)(
    tapi_iomux_handle *iomux,
    int fd
    )

Function prototype to delete a file descriptor from a multiplexer set.

Parameters:

iomux	The multiplexer handle.
fd	The file descriptor which should be deleted.

typedef int (*tapi_iomux_method_call)(
    tapi_iomux_handle *iomux,
    int timeout,
    tapi_iomux_evt_fd **revts
    )

Function prototype to perform a multiplexer call.

Parameters:

iomux	The multiplexer handle.
timeout	Timeout to block in the call in milliseconds.
revts	Returned events.

Returns:

Events number or -1 in case of fail, actualy return code is forwarded from the system multiplexer function call.

typedef void (*tapi_iomux_method_destroy)(tapi_iomux_handle *iomux)

Function prototype to destroy a multiplexer.

Parameters:

iomux

The multiplexer handle.

typedef struct tapi_iomux_methods tapi_iomux_methods

A multiplexer methods.

typedef struct tapi_iomux_select_context tapi_iomux_select_context

Context data for select() API.

typedef struct tapi_iomux_poll_context tapi_iomux_poll_context

Context data for poll() API.

typedef struct tapi_iomux_epoll_context tapi_iomux_epoll_context

Context data for epoll() API.

typedef struct tapi_iomux_evts_list tapi_iomux_evts_list

Events list for internal iomux API using.

Global Functions

RPCBITMAP2STR(tapi_iomux_event, IOMUX_EVENT_MAPPING_LIST)

tapi_iomux_event_rpc2str()

tapi_iomux_type tapi_iomux_call_str2en(const char* iomux)

Convert string name of iomux function to enum constant.

Parameters:

iomux

name of function: “select”, “pselect”, or “poll”.

Returns:

respective value from tapi_iomux_type enum.

const char* tapi_iomux_call_en2str(tapi_iomux_type iomux_type)

Convert constant from tapi_iomux_type to human string

Parameters:

iomux_type

Value to be converted

Returns:

static character string

short int tapi_iomux_evt_to_poll(tapi_iomux_evt iomux_evt_mask)

Convert bitmask constructed with constants from tapi_iomux_evt type to bitmask constructed with standard POLL* macros from poll.h

Parameters:

iomux_evt_mask

Event bitmask from tapi_iomux_evt constants.

Returns:

event bitmask from POLL* constants.

uint32_t tapi_iomux_evt_to_epoll(tapi_iomux_evt iomux_evt_mask)

Convert bitmask constructed with constants from tapi_iomux_evt type to bitmask constructed with standard EPOLL* macros from epoll.h

Parameters:

iomux_evt_mask

Event bitmask from tapi_iomux_evt constants.

Returns:

event bitmask from EPOLL* constants.

tapi_iomux_evt tapi_iomux_poll_to_evt(short int poll_evt_mask)

Convert bitmask constructed with standard POLL* macros from poll.h to bitmask constructed with constants from tapi_iomux_evt type.

Parameters:

poll_evt_mask

event bitmask from POLL* constants.

Returns:

event bitmask from tapi_iomux_evt constants.

tapi_iomux_evt tapi_iomux_epoll_to_evt(uint32_t epoll_evt_mask)

Convert bitmask constructed with standard EPOLL* macros from epoll.h to bitmask constructed with constants from tapi_iomux_evt type.

Parameters:

epoll_evt_mask

event bitmask from EPOLL* constants.

Returns:

event bitmask from tapi_iomux_evt constants.

tapi_iomux_handle* tapi_iomux_create(rcf_rpc_server* rpcs, tapi_iomux_type type)

Create a multiplexer.

Parameters:

rpcs	RPC server handle.
type	The multiplexer type.

Returns:

The multiplexer handle.

void tapi_iomux_add(tapi_iomux_handle* iomux, int fd, tapi_iomux_evt evt)

Add a file descriptor to a multiplexer set.

Parameters:

iomux	The multiplexer handle.
fd	The file descriptor to add to the multiplexer set.
evt	Requested events.

void tapi_iomux_mod(tapi_iomux_handle* iomux, int fd, tapi_iomux_evt evt)

Modify a file descriptor events.

Parameters:

iomux	The multiplexer handle.
fd	The file descriptor to modify events for.
evt	New events.

void tapi_iomux_del(tapi_iomux_handle* iomux, int fd)

Delete a file descriptor from a multiplexer set.

Parameters:

iomux	The multiplexer handle.
fd	The file descriptor which should be deleted.

void tapi_iomux_set_sigmask(tapi_iomux_handle* iomux, rpc_sigset_p sigmask)

Specify a signal mask for a multiplexer.

This call makes sense for iomux types TAPI_IOMUX_PSELECT, TAPI_IOMUX_PPOLL, TAPI_IOMUX_EPOLL_PWAIT and TAPI_IOMUX_EPOLL_PWAIT2, the signal mask is ignored by other muxers.

Parameters:

iomux	The multiplexer handle.
sigmask	RPC pointer to the signal mask.

int tapi_iomux_call(tapi_iomux_handle* iomux, int timeout, tapi_iomux_evt_fd** revts)

Perform a multiplexer call.

The call can be done expecting a fail using RPC_AWAIT_IUT_ERROR as for usual RPC call, return code of the muxer call is forwarded and returned by the function.

This call can be executed in non-blocking mode using RCF_RPC_CALL as usual RPC call.

Parameters:

iomux	The multiplexer handle.
timeout	Timeout to block in the call in milliseconds.
revts	Returned events.

Returns:

Events number or -1 in case of fail, actualy return code is forwarded from the system multiplexer function call.

int tapi_iomux_pcall(tapi_iomux_handle* iomux, int timeout, rpc_sigset_p sigmask, tapi_iomux_evt_fd** revts)

Perform a multiplexer call specifying a signal mask.

See also tapi_iomux_call() description for details.

Parameters:

iomux	The multiplexer handle.
timeout	Timeout to block in the call in milliseconds.
sigmask	Signal mask.
revts	Returned events.

Returns:

Events number or -1 in case of fail, actualy return code is forwarded from the system multiplexer function call.

void tapi_iomux_destroy(tapi_iomux_handle* iomux)

Destroy a multiplexer.

Parameters:

iomux

The multiplexer handle.

tapi_iomux_evt_fd* tapi_iomux_epoll_get_events(tapi_iomux_handle* iomux, struct rpc_epoll_event* events, int evts_num)

Process returned events by epoll_wait(), epoll_pwait() or epoll_pwait2() call, convert and save them in the iomux context.

Parameters:

iomux	The multiplexer handle.
events	Returned epoll events array.
evts_num	The array length.

Returns:

Returned events array converted to the generic representation.

Macros

#define BIT_MAP_ENTRY(entry_val_)

Define one entry in the list of maping entries

#define IOMUX_EVENT_MAPPING_LIST

List of mapping numerical value to string for ‘tapi_iomux_evt’

#define TAPI_IOMUX_MAPPING_LIST

The list of values allowed for test parameter defining iomux function.

#define TAPI_IOMUX_MAX

Maximum supported iomux type value.

#define TAPI_IOMUX_MIN

Minimum supported iomux type value.

#define TEST_GET_TE_IOMUX_FUNC(var_name_)

Get the value of parameter defining iomux function.

Parameters:

var_name_

Name of the variable used to get the value of “var_name_” parameter.