pxcloud/spice
6
0
Fork 0
mirror of https://gitlab.uni-freiburg.de/opensourcevdi/spice synced 2026-08-15 00:08:52 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

dispatcher: Update documentation

Browse Source 
Move to Doxygen (output was not meant to generate output
automatically).
Update some part that were outdated.
Typo messsage_type -> message_type.

Signed-off-by: Frediano Ziglio <freddy77@gmail.com>
Acked-by: Julien Ropé <jrope@gmail.com>
This commit is contained in:
Frediano Ziglio 2020-06-10 15:31:53 +01:00
parent f64ace4e34
commit 4c25ce1877
1 changed files with 45 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
server/dispatcher.h
View File

@ -40,7 +40,8 @@ typedef void (*dispatcher_handle_any_message)(void *opaque,
uint32_t message_type,
void *payload);
/* A Dispatcher provides inter-thread communication by serializing messages.
/**
* A Dispatcher provides inter-thread communication by serializing messages.
* Currently the Dispatcher uses a unix socket (socketpair) for dispatching the
* messages.
*
@ -48,51 +49,59 @@ typedef void (*dispatcher_handle_any_message)(void *opaque,
* registered with the class (see register_handler()) before they
* can be sent. Sending threads can send a message using the
* send_message() function. The receiving thread can monitor the
* dispatcher's 'receive' file descriptor (see dispatcher_get_recv_fd()) for
* activity and should call dispatcher_handle_recv_read() to process incoming
* messages.
* dispatcher's 'receive' file descriptor (see create_watch()) for
* activity and to process incoming messages.
*/
class Dispatcher: public red::shared_ptr_counted
{
public:
/* Create a new Dispatcher object
/**
* Create a new Dispatcher object
*
* @max_message_type: indicates the number of unique message types that can
* be handled by this dispatcher. Each message type is
* identified by an integer value between 0 and
* max_message_type-1.
* @param max_message_type: indicates the number of unique message types that can
* be handled by this dispatcher. Each message type is
* identified by an integer value between 0 and
* max_message_type-1.
*/
Dispatcher(uint32_t max_message_type);
/* send_message
*
/**
* Sends a message to the receiving thread. The message type must have been
* registered first (see register_handler()). @payload must be a
* buffer of the same size as the size registered for @message_type
* registered first (see register_handler()). @p payload must be a
* buffer of the same size as the size registered for @p message_type
*
* If the sent message is a message type requires an ACK, this function will
* block until it receives an ACK from the receiving thread.
*
* @message_type: message type
* @payload: payload
* @param message_type: message type
* @param payload: payload
*/
void send_message(uint32_t message_type, void *payload);
/* send_message_custom
*
/**
* Sends a message to the receiving thread.
*
* If the sent message requires an ACK, this function will block until it
* receives an ACK from the receiving thread.
*
* @handler: callback to handle message
* @payload: payload
* @payload_size: size of payload
* @ack: acknowledge required. Make message synchronous
* @param handler: callback to handle message
* @param[in] payload: payload
* @param payload_size: size of payload
* @param ack: acknowledge required. Make message synchronous
*/
void send_message_custom(dispatcher_handle_message handler,
void *payload, uint32_t payload_size, bool ack);
/**
* Sends a message to the receiving thread.
*
* If the sent message requires an ACK, this function will block until it
* receives an ACK from the receiving thread.
*
* @param handler: callback to handle message
* @param[in] payload: payload
* @param ack: acknowledge required. Make message synchronous
*/
template <typename T> inline void
send_message_custom(void (*handler)(void *, T*), T *payload, bool ack)
{
@ -100,26 +109,24 @@ public:
payload, sizeof(*payload), ack);
}
/* register_handler
*
/**
* This function registers a message type with the dispatcher, and registers
* @handler as the function that will handle incoming messages of this type.
* If @ack is true, the dispatcher will also send an ACK in response to the
* @p handler as the function that will handle incoming messages of this type.
* If @p ack is true, the dispatcher will also send an ACK in response to the
* message after the message has been passed to the handler. You can only
* register a given message type once. For example, you cannot register two
* different handlers for the same message type with different @ack values.
* different handlers for the same message type with different @p ack values.
*
* @messsage_type: message type
* @handler: message handler
* @size: message size. Each type has a fixed associated size.
* @ack: whether the dispatcher should send an ACK to the sender
* @param message_type: message type
* @param handler: message handler
* @param size: message size. Each type has a fixed associated size.
* @param ack: whether the dispatcher should send an ACK to the sender
*/
void register_handler(uint32_t message_type,
dispatcher_handle_message handler, size_t size,
bool ack);
/* register_universal_handler
*
/**
* Register a universal handler that will be called when *any* message is
* received by the dispatcher. When a message is received, this handler will be
* called first. If the received message type was registered via
@ -127,25 +134,23 @@ public:
* called. Only one universal handler can be registered. This feature can be
* used to record all messages to a file for replay and debugging.
*
* @handler: a handler function
* @param handler: a handler function
*/
void register_universal_handler(dispatcher_handle_any_message handler);
/* create_watch
*
/**
* Create a new watch to handle events for the dispatcher.
* You should release it before releasing the dispatcher.
*
* @return: newly created watch
* @return newly created watch
*/
SpiceWatch *create_watch(SpiceCoreInterfaceInternal *core);
/* set_opaque
*
* This @opaque pointer is user-defined data that will be passed as the first
/**
* This @p opaque pointer is user-defined data that will be passed as the first
* argument to all handler functions.
*
* @opaque: opaque to use for callbacks
* @param opaque: opaque to use for callbacks
*/
void set_opaque(void *opaque);