Martti Mela <Martti.Mela@nokia-email.address.hidden>
#include <sys/poll.h>
#include "sofia-sip/su.h"
#include "sofia-sip/su_time.h"
Include dependency graph for su_wait.h:

Go to the source code of this file.
Defines | |
| #define | SU_WAIT_CMP(x, y) |
| Compare wait object. | |
| #define | SU_WAIT_IN |
| Incoming data is available on socket. | |
| #define | SU_WAIT_OUT |
| Data can be sent on socket. | |
| #define | SU_WAIT_CONNECT |
| Socket is connected. | |
| #define | SU_WAIT_ERR |
| An error occurred on socket. | |
| #define | SU_WAIT_HUP |
| The socket connection was closed. | |
| #define | SU_WAIT_ACCEPT |
| A listening socket accepted a new connection. | |
| #define | SU_WAIT_FOREVER |
| No timeout for su_wait(). | |
| #define | SU_WAIT_TIMEOUT |
| The return value of su_wait() if timeout occurred. | |
| #define | SU_WAIT_INIT |
| Initializer for a wait object. | |
| #define | SU_WAIT_MAX |
| Maximum number of sources supported by su_wait(). | |
| #define | SU_ROOT_MAGIC_T |
| Default type of application context for su_root_t. | |
| #define | SU_WAKEUP_ARG_T |
| Default type of wakeup function argument type . | |
| #define | SU_PREPOLL_MAGIC_T |
| Default type of application context for prepoll function. | |
| #define | SU_TIMER_ARG_T |
| Default type of timer expiration callback function argument type. | |
| #define | SU_TASK_R_INIT |
| Initializer for a task reference. | |
| #define | SU_MSG_ARG_T |
| Default type of su_msg_t message data. | |
| #define | SU_MSG_R_INIT |
| Initializer for a message reference. | |
| #define | SU_CLONE_R_INIT |
| Clone reference initializer. | |
Typedefs | |
| typedef pollfd | su_wait_t |
| Wait object. | |
| typedef su_root_t | su_root_t |
| Root object type. | |
| typedef SU_ROOT_MAGIC_T | su_root_magic_t |
| Root context pointer type. | |
| typedef SU_WAKEUP_ARG_T | su_wakeup_arg_t |
| Wakeup callback argument type. | |
| typedef int(* | su_wakeup_f )(su_root_magic_t *, su_wait_t *, su_wakeup_arg_t *arg) |
| Wakeup callback function pointer type. | |
| typedef SU_PREPOLL_MAGIC_T | su_prepoll_magic_t |
| Root context pointer type. | |
| typedef void | su_prepoll_f (su_prepoll_magic_t *, su_root_t *) |
| Pre-poll callback function prototype. | |
| typedef su_timer_s | su_timer_t |
| Timer object type. | |
| typedef SU_TIMER_ARG_T | su_timer_arg_t |
| Timer callback argument type. | |
| typedef void(* | su_timer_f )(su_root_magic_t *magic, su_timer_t *t, su_timer_arg_t *arg) |
| Timeout function type. | |
| typedef su_port_s | su_port_t |
| Port type. | |
| typedef _su_task_t | su_task_r [1] |
| Task reference type. | |
| typedef SU_MSG_ARG_T | su_msg_arg_t |
| Message argument type. | |
| typedef su_msg_s | su_msg_t |
| Message type. | |
| typedef su_msg_t * | su_msg_r [1] |
| Message reference type. | |
| typedef su_msg_t *const | su_msg_cr [1] |
| Constant reference to su_msg. | |
| typedef void | su_msg_function (su_root_magic_t *magic, su_msg_r msg, su_msg_arg_t *arg) |
| Message delivery function type. | |
| typedef void | su_msg_deinit_function (su_msg_arg_t *arg) |
| Message deinitializer function type. | |
| typedef su_msg_function * | su_msg_f |
| Message delivery function pointer type. | |
| typedef SU_CLONE_T * | su_clone_r [1] |
| Clone reference. | |
| typedef int(* | su_root_init_f )(su_root_t *, su_root_magic_t *) |
| Clone initialization function type. | |
| typedef void(* | su_root_deinit_f )(su_root_t *, su_root_magic_t *) |
| Clone finalization function type. | |
Enumerations | |
| enum | { su_pri_normal, su_pri_first, su_pri_realtime } |
Functions | |
| void | su_wait_init (su_wait_t dst[1]) |
| Initialize a wait object. | |
| int | su_wait_create (su_wait_t *dst, su_socket_t s, int events) |
| Create a wait object. | |
| int | su_wait_destroy (su_wait_t *dst) |
| Destroy a wait object. | |
| int | su_wait (su_wait_t waits[], unsigned n, su_duration_t timeout) |
| Wait for multiple events. | |
| int | su_wait_events (su_wait_t *wait, su_socket_t s) |
| Get events. | |
| int | su_wait_mask (su_wait_t *dst, su_socket_t s, int events) |
| Set event mask. | |
| su_root_t * | su_root_create (su_root_magic_t *magic)) |
| Create a reactor object. | |
| void | su_root_destroy (su_root_t *) |
| Destroy a root object. | |
| char const * | su_root_name (su_root_t *self) |
| Get instance name. | |
| int | su_root_set_magic (su_root_t *self, su_root_magic_t *magic) |
| Set the context pointer. | |
| su_root_magic_t * | su_root_magic (su_root_t *root) |
| Get context pointer. | |
| int | su_root_register (su_root_t *, su_wait_t *, su_wakeup_f, su_wakeup_arg_t *, int priority) |
| Register a su_wait_t object. | |
| int | su_root_unregister (su_root_t *, su_wait_t *, su_wakeup_f, su_wakeup_arg_t *) |
| Unregister a su_wait_t object. | |
| int | su_root_deregister (su_root_t *, int) |
| Remove a su_wait_t registration. | |
| int | su_root_eventmask (su_root_t *, int index, int socket, int events) |
| Set mask for a registered event. | |
| su_duration_t | su_root_step (su_root_t *root, su_duration_t timeout) |
| Process events, timers and messages. | |
| su_duration_t | su_root_sleep (su_root_t *root, su_duration_t) |
| Run event and message loop for given duration. | |
| int | su_root_multishot (su_root_t *root, int multishot) |
| Set multishot mode. | |
| void | su_root_run (su_root_t *root) |
| Run event and message loop. | |
| void | su_root_break (su_root_t *root) |
| Terminate event loop. | |
| su_task_r | su_root_task (su_root_t const *root) |
| Get task reference. | |
| su_task_r | su_root_parent (su_root_t const *root) |
| Get parent task reference. | |
| int | su_root_add_prepoll (su_root_t *root, su_prepoll_f *, su_prepoll_magic_t *) |
| Add a pre-poll callback. | |
| int | su_root_remove_prepoll (su_root_t *root) |
| Remove a pre-poll callback. | |
| _GSource * | su_root_gsource (su_root_t *self) |
| Get a GSource. | |
| int | su_root_yield (su_root_t *root) |
| Check wait events in callbacks that take lots of time. | |
| int | su_root_release (su_root_t *root) |
| Release the root port for other threads. | |
| int | su_root_obtain (su_root_t *root) |
| Obtain the root port from other thread. | |
| int | su_root_has_thread (su_root_t *root) |
| Check if a thread has obtained the root. | |
| su_timer_t * | su_timer_create (su_task_r const, su_duration_t msec)) |
| Create a timer. | |
| void | su_timer_destroy (su_timer_t *) |
| Destroy a timer. | |
| int | su_timer_set (su_timer_t *, su_timer_f, su_timer_arg_t *) |
| Set the timer for the default interval. | |
| int | su_timer_set_interval (su_timer_t *t, su_timer_f, su_timer_arg_t *, su_duration_t) |
| Set the timer for the given interval. | |
| int | su_timer_run (su_timer_t *, su_timer_f, su_timer_arg_t *) |
| Set the timer for regular intervals. | |
| int | su_timer_set_for_ever (su_timer_t *, su_timer_f, su_timer_arg_t *) |
| Set the timer for regular intervals. | |
| int | su_timer_reset (su_timer_t *) |
| Reset the timer. | |
| su_root_t * | su_timer_root (su_timer_t const *) |
| Get the root object owning the timer. | |
| su_task_r | su_task_init (su_task_r task) |
| Initialize a task handle with su_task_null. | |
| void | su_task_deinit (su_task_r task) |
| Destroy a task handle. | |
| void | su_task_copy (su_task_r dst, su_task_r const src) |
| Duplicates a task handle. | |
| void | su_task_move (su_task_r dst, su_task_r src) |
| Moves a task handle. | |
| int | su_task_cmp (su_task_r const, su_task_r const) |
| Compare two tasks with each other. | |
| int | su_task_is_running (su_task_r const) |
| Tests if a task is running. | |
| su_root_t * | su_task_root (su_task_r const self) |
| Get root pointer attached to a task handle. | |
| su_timer_queue_t * | su_task_timers (su_task_r const self) |
| Return the timer list associated with given task. | |
| int | su_task_execute (su_task_r const task, int(*function)(void *), void *arg, int *return_value) |
| Execute the function by task thread. | |
| int | su_msg_create (su_msg_r msg, su_task_r const to, su_task_r const from, su_msg_f wakeup, isize_t size) |
| Allocates a message of given size. | |
| int | su_msg_report (su_msg_r msg, su_msg_f report) |
| Add a delivery report function to a message. | |
| int | su_msg_deinitializer (su_msg_r msg, su_msg_deinit_function *) |
| Add a deinitializer function to a message. | |
| int | su_msg_reply (su_msg_r reply, su_msg_cr msg, su_msg_f wakeup, isize_t size) |
| Allocates a reply message of given size. | |
| void | su_msg_destroy (su_msg_r msg) |
| Destroys an unsent message. | |
| void | su_msg_save (su_msg_r msg, su_msg_r msg0) |
| Save a message. | |
| void | su_msg_remove_refs (su_msg_cr msg) |
| Remove references to 'from' and 'to' tasks from a message. | |
| su_msg_arg_t * | su_msg_data (su_msg_cr msg) |
| Gets a pointer to the message data area. | |
| isize_t | su_msg_size (su_msg_cr msg) |
| Get size of message data area. | |
| su_task_r | su_msg_from (su_msg_cr msg) |
| Get sending task. | |
| su_task_r | su_msg_to (su_msg_cr msg) |
| Get destination task. | |
| int | su_msg_send (su_msg_r msg) |
| Send a message. | |
| int | su_msg_new (su_msg_r msg, size_t size) |
| Allocate a su message of given size. | |
| int | su_msg_send_to (su_msg_r msg, su_task_r const to, su_msg_f wakeup) |
| Send message to the to_task and mark from_task as sender. | |
| int | su_root_threading (su_root_t *self, int enable) |
| Set threading option. | |
| int | su_clone_start (su_root_t *root, su_clone_r, su_root_magic_t *magic, su_root_init_f, su_root_deinit_f) |
| Start a clone task. | |
| su_task_r | su_clone_task (su_clone_r) |
| Get reference to a clone task. | |
| void | su_clone_forget (su_clone_r) |
| Forget the clone. | |
| void | su_clone_stop (su_clone_r) |
| Stop the clone. | |
| void | su_clone_wait (su_root_t *root, su_clone_r clone) |
| Stop a clone and wait until it is has completed. | |
| int | su_clone_pause (su_clone_r) |
| Pause a clone. | |
| int | su_clone_resume (su_clone_r) |
| Resume a clone. | |
| void | su_port_prefer (su_port_create_f *f, su_clone_start_f *) |
| Explicitly set the preferred su_port_t implementation. | |
Variables | |
| int | su_root_size_hint |
| Hint for number of registered fds in su_root. | |
| su_task_r const | su_task_null |
| NULL task. | |
|
|
Default type of su_msg_t message data. Application may define this to appropriate type before including <sofia-sip/su_wait.h>. |
|
|
Default type of application context for prepoll function. Application may define the typedef su_prepoll_magic_t to appropriate type by defining macro SU_PREPOLL_MAGIC_T before including <sofia-sip/su_wait.h>, for example, #define SU_PREPOLL_MAGIC_T struct context #include <sofia-sip/su_wait.h> |
|
|
Default type of application context for su_root_t. Application may define the typedef su_root_magic_t to appropriate type by defining macro SU_ROOT_MAGIC_T before including <sofia-sip/su_wait.h>, for example, #define SU_ROOT_MAGIC_T struct context f * #include <sofia-sip/su_wait.h> |
|
|
Default type of timer expiration callback function argument type. Application may define this to appropriate type before including <sofia-sip/su_wait.h>. |
|
|
Default type of wakeup function argument type . The application can define the typedef su_wakeup_arg_t by defining the SU_WAKEUP_ARG_T () before including <sofia-sip/su_wait.h>, for example, #define SU_WAKEUP_ARG_T struct transport #include <sofia-sip/su_wait.h> |
|
|
Constant reference to su_msg.
|
|
|
Message deinitializer function type.
|
|
|
Root context pointer type. Application may define the typedef su_prepoll_magic_t to appropriate type by defining macro SU_PREPOLL_MAGIC_T before including <sofia-sip/su_wait.h>, for example, #define SU_PREPOLL_MAGIC_T struct context #include <sofia-sip/su_wait.h> |
|
|
Root context pointer type. Application may define the typedef su_root_magic_t to appropriate type by defining macro SU_ROOT_MAGIC_T () before including <sofia-sip/su_wait.h>, for example, #define SU_ROOT_MAGIC_T struct context #include <sofia-sip/su_wait.h> |
|
|
Wakeup callback argument type. The application can define the typedef su_wakeup_arg_t by defining the SU_WAKEUP_ARG_T () before including <sofia-sip/su_wait.h>, for example, #define SU_WAKEUP_ARG_T struct transport #include <sofia-sip/su_wait.h> |
|
|
Wakeup callback function pointer type. Whenever a registered wait object receives an event, the callback function is invoked. |
|
|
|
|
|
Forget the clone. Normally, the clone task executes until it is stopped. If the parent task does not need to stop the task, it can "forget" the clone. The clone exits independently of the parent task.
|
|
|
Pause a clone. Obtain an exclusive lock on clone's private data.
|
|
|
Resume a clone. Give up an exclusive lock on clone's private data.
|
|
||||||||||||||||||||||||
|
Start a clone task. Allocate and initialize a sub-task. Depending on the su_root_threading() settings, a separate thread may be created to execute the sub-task. The sub-task is represented by clone handle to the rest of the application. The function su_clone_start() returns the clone handle in return_clone. The clone handle is used to communicate with the newly created clone task using messages. A new su_root_t object is created for the sub-task with the magic as the root context pointer. Because the sub-task may or may not have its own thread, all its activity must be scheduled via this root object. In other words, the sub-task can be schedule
Messages can also be used to pass information between tasks or threads. In multi-threaded implementation, su_clone_start() launches a new thread, and the initialization routine is executed by this newly created thread. The calling thread blocks until the initialization routine completes. If the initialization routine returns su_success (0), the sub-task is considered to be created successfully. After the successful initialization, the sub-task continues to execeute the function su_root_run(). In single-threaded implementations, just a new root object is created. The initialization routine is called directly from su_clone_start(). If the initalization function init fails, the sub-task (either the newly created thread or the current thread executing the su_clone_start() function) calls the deinitialization function, and su_clone_start() returns NULL.
|
|
|
Stop the clone. This can used only if clone task has sent no report messages (messages with delivery report sent back to clone).
|
|
|
Get reference to a clone task.
|
|
||||||||||||
|
Stop a clone and wait until it is has completed. The function su_clone_wait() is used to stop the clone task and wait until it has cleaned up. The clone task is destroyed asynchronously. The parent sends a message to clone, clone deinitializes itself and then replies. After the reply message is received by the parent, it will send a third message back to clone. The parent destroy all messages to or from clone task before calling su_clone_wait(). The parent task may not send any messages to the clone after calling su_clone_wait(). The su_clone_wait() function blocks until the cloned task is destroyed. During that time, the parent task must be prepared to process all the messages sent by clone task. This includes all the messages sent by clone before destroy the message reached the clone. |
|
||||||||||||||||||||||||
|
Allocates a message of given size.
The function
|
|
|
Gets a pointer to the message data area.
The function
|
|
||||||||||||
|
Add a deinitializer function to a message. The deinitializer function is called when the message gets destroyed. It is called even if the message was never delivered. Note that the thread destroying the message and calling the deinit function is not necessarily the same that sent the message nor the original recipient.
|
|
|
Destroys an unsent message.
|
|
|
Get sending task. Returns the task handle belonging to the sender of the message.
If the message handle contains NULL the function
|
|
||||||||||||
|
Allocate a su message of given size. Allocate a su message with given data size.
|
|
|
Remove references to 'from' and 'to' tasks from a message.
|
|
||||||||||||||||||||
|
Allocates a reply message of given size.
|
|
||||||||||||
|
Add a delivery report function to a message. The delivery report funcgtion gets called by the sending task after the message was delivered and the message function was executed. (The su_root_t message delivery loop calls su_msg_delivery_report() |
|
|
Send a message.
The function
|
|
||||||||||||||||
|
Send message to the to_task and mark from_task as sender.
|
|
|
Get destination task.
The function
If the message handle contains NULL the function
|
|
||||||||||||
|
Explicitly set the preferred su_port_t implementation.
|
|
|
Terminate event loop. The function su_root_break() is used to terminate execution of su_root_run(). It can be called from a callback function.
|
|
|
Create a reactor object. Allocate and initialize the instance of su_root_t.
|
|
||||||||||||
|
Remove a su_wait_t registration. The function su_root_deregister() deregisters a su_wait_t object. The wait object, a callback function and a argument are removed from the root object. The wait object is destroyed.
|
|
|
Destroy a root object. Stop and free an instance of su_root_t
|
|
||||||||||||||||||||
|
Set mask for a registered event. The function su_root_eventmask() sets the mask describing events that can signal the registered callback.
|
|
|
Check if a thread has obtained the root.
|
|
|
Get context pointer. The function su_root_magic() returns the user context pointer that was given input to su_root_create() or su_root_set_magic().
|
|
||||||||||||
|
Set multishot mode. The function su_root_multishot() enables, disables or queries the multishot mode for the root. The multishot mode determines how the events are scheduled by root. If multishot mode is enabled, root serves all the sockets that have received network events. If it is disables, only first socket event is served.
|