Loading...
Searching...
No Matches
su_wait.h File Reference
Syncronization and Threading

Syncronization and threading interface. More...

`#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.

## Macros

#define | SU_WAIT_H
| Defined when <sofia-sip/su_wait.h> has been included.
#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 struct pollfd | su_wait_t
| Wait object.
typedef struct 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 struct 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 struct 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 struct 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.
struct _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.
int | su_root_set_max_defer (su_root_t *, su_duration_t max_defer)
| Set maximum defer time.
su_duration_t | su_root_get_max_defer (su_root_t const *self)
| Get maximum defer time.
su_time64_t | su_root_stamp64 (su_root_t const *)
| Get cached timestamp.
su_dur64_t | su_root_stamp64_offset (su_root_t const *)
| Get cached offset between monotonic timestamps and UTC time.
su_root_t * | su_root_clone (su_root_t *root, su_root_magic_t *magic))
| Create a a new root object sharing port/thread with existing one.
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_is_set (su_timer_t const *t)
| Check if the timer has been set.
su_time_t | su_timer_latest (su_timer_t const *t)
| Return when the timer has been last expired.
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.
int | su_timer_deferrable (su_timer_t *t, int value)
| Change timer as deferrable (or as undeferrable).
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.
su_timer_queue_t * | su_task_deferrable (su_task_r const task)
| Return the queue for deferrable timers associated with given task.
int | su_task_wakeup (su_task_r const task)
| Wakeup a 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.

## Detailed Description

Syncronization and threading interface.

Author
  Pekka Pessi Pekka.nosp@m..Pes.nosp@m.si@no.nosp@m.kia..nosp@m.com
  Martti Mela Martt.nosp@m.i.Me.nosp@m.la@no.nosp@m.kia..nosp@m.com

Date
  Created: Tue Sep 14 15:51:04 1999 ppessi

## Macro Definition Documentation

## SU_MSG_ARG_T

#define SU_MSG_ARG_T

Default type of su_msg_t message data.

Application may define this to appropriate type before including <sofia-sip/su_wait.h>.

## SU_PREPOLL_MAGIC_T

#define SU_PREPOLL_MAGIC_T

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>
su_wait.h
Syncronization and threading interface.

## SU_ROOT_MAGIC_T

#define SU_ROOT_MAGIC_T

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>
su_wait
int su_wait(su_wait_t waits[], unsigned n, su_duration_t timeout)
Wait for multiple events.
Definition su_wait.c:222

## SU_TIMER_ARG_T

#define SU_TIMER_ARG_T

Default type of timer expiration callback function argument type.

Application may define this to appropriate type before including <sofia-sip/su_wait.h>.

## SU_WAKEUP_ARG_T

#define SU_WAKEUP_ARG_T

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>

## Typedef Documentation

## su_msg_cr

typedef su_msg_t* const su_msg_cr[1]

Constant reference to su_msg.

Note
  The reference is constant, but the message can be modified.

## su_msg_deinit_function

typedef void su_msg_deinit_function(su_msg_arg_t *arg)

Message deinitializer function type.

Since
  New in 1.12.8

## su_prepoll_magic_t

typedef SU_PREPOLL_MAGIC_T su_prepoll_magic_t

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>

## su_root_magic_t

typedef SU_ROOT_MAGIC_T su_root_magic_t

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>

## su_wakeup_arg_t

typedef SU_WAKEUP_ARG_T su_wakeup_arg_t

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>

## su_wakeup_f

typedef int(* su_wakeup_f) (su_root_magic_t *, su_wait_t *, su_wakeup_arg_t *arg)

Wakeup callback function pointer type.

Whenever a registered wait object receives an event, the callback function is invoked.

## Enumeration Type Documentation

## anonymous enum

anonymous enum

Enumerator
su_pri_normal | Normal priority.
su_pri_first | Elevated priority.
su_pri_realtime | Real-time priority.

## Function Documentation

## su_clone_forget()

void su_clone_forget | ( | su_clone_r | rclone | ) |

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.

Parameters

  rclone | Reference to the clone.

## su_clone_pause()

int su_clone_pause | ( | su_clone_r | rclone | ) |

Pause a clone.

Obtain an exclusive lock on clone's private data.

Return values

  0 | if successful (and clone is paused)
  -1 | upon an error

Deprecated
  Never implemented.

## su_clone_resume()

int su_clone_resume | ( | su_clone_r | rclone | ) |

Resume a clone.

Give up an exclusive lock on clone's private data.

Return values

  0 | if successful (and clone is resumed)
  -1 | upon an error

Deprecated
  Never implemented.

## su_clone_start()

int su_clone_start | ( | su_root_t * | parent,
|  | su_clone_r | return_clone,
|  | su_root_magic_t * | magic,
|  | su_root_init_f | init,
|  | su_root_deinit_f | deinit )

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

1. I/O events with su_root_register()
2. timers with su_timer_set(), su_timer_set_at() or su_timer_run()
3. messages with su_msg_send().

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.

Parameters

  parent | root to be cloned
  return_clone | reference to a clone [OUT]
  magic | pointer to user data
  init | initialization function
  deinit | deinitialization function

Returns
  0 if successfull, -1 upon an error.

Note
  Earlier documentation mentioned that parent could be NULL. That feature has never been implemented, however.

See also
  su_root_threading(), su_clone_task(), su_clone_stop(), su_clone_wait(), su_clone_forget().

## su_clone_stop()

void su_clone_stop | ( | su_clone_r | rclone | ) |

Stop the clone.

This can used only if clone task has sent no report messages (messages with delivery report sent back to clone).

Deprecated
  . Use su_clone_wait().

## su_clone_task()

su_task_r su_clone_task | ( | su_clone_r | clone | ) |

Get reference to a clone task.

Parameters

  clone | Clone pointer

Returns
  A reference to the task structure of the clone.

## su_clone_wait()

void su_clone_wait | ( | su_root_t * | root,
|  | su_clone_r | rclone )

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.

## su_msg_create()

int su_msg_create | ( | su_msg_r | rmsg,
|  | su_task_r const | to,
|  | su_task_r const | from,
|  | su_msg_f | wakeup,
|  | isize_t | size )

Allocates a message of given size.

The function `su_msg_create()` allocates a message with given data size. If successful, it moves the new message handle to the `rmsg`.

Parameters

  rmsg | handle to the new message (may be uninitialized prior calling)
  to | the recipient task
  from | the sender task
  wakeup | function that is called when message is delivered
  size | size of the message data

Return values

  0 | if successful,
  -1 | if message allocation fails.

## su_msg_data()

su_msg_arg_t * su_msg_data | ( | su_msg_cr | rmsg | ) |

Gets a pointer to the message data area.

The function `su_msg_data()` returns a pointer to the message data area. If `rmsg` contains a `NULL` handle, or message size is 0, `NULL` pointer is returned.

Parameters

  rmsg | message handle

Returns
  A pointer to the message data area is returned.

## su_msg_deinitializer()

int su_msg_deinitializer | ( | su_msg_r | rmsg,
|  | su_msg_deinit_function * | deinit )

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.

Parameters

  rmsg | message reference
  deinit | pointer to deinitializer function

Since
  New in 1.12.8

## su_msg_destroy()

void su_msg_destroy | ( | su_msg_r | rmsg | ) |

Destroys an unsent message.

Parameters

  rmsg | message handle.

## su_msg_from()

su_task_r su_msg_from | ( | su_msg_cr | rmsg | ) |

Get sending task.

Returns the task handle belonging to the sender of the message.

If the message handle contains NULL the function `su_msg_from` returns NULL.

Parameters

  rmsg | message handle

Returns
  The task handle of the sender is returned.

## su_msg_new()

int su_msg_new | ( | su_msg_r | rmsg,
|  | size_t | size )

Allocate a su message of given size.

Allocate a su message with given data size.

Parameters

  rmsg | handle to the new message (may be uninitialized prior calling)
  size | size of the message data

Return values

  0 | if successful,
  -1 | if message allocation fails.

Since
  New in 1.12.8

## su_msg_remove_refs()

void su_msg_remove_refs | ( | su_msg_cr | rmsg | ) |

Remove references to 'from' and 'to' tasks from a message.

Parameters

  rmsg | message handle

## su_msg_reply()

int su_msg_reply | ( | su_msg_r | reply,
|  | su_msg_cr | rmsg,
|  | su_msg_f | wakeup,
|  | isize_t | size )

Allocates a reply message of given size.

Parameters

  reply | handle to the new message (may be uninitialized prior calling)
  rmsg | the incoming message
  wakeup | function that is called when message is delivered
  size | size of the message data

Return values

  0 | if successful,
  -1 | otherwise.

## su_msg_report()

int su_msg_report | ( | su_msg_r | msg,
|  | su_msg_f | report )

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()

## su_msg_send()

int su_msg_send | ( | su_msg_r | rmsg | ) |

Send a message.

The function `su_msg_send()` sends the message. The message is added to the recipients message queue, and recipient is waken up. The caller may not alter the message or the data associated with it after the message has been sent.

Parameters

  rmsg | message handle

Return values

  0 | if signal was sent successfully or handle was `NULL`,
  -1 | otherwise.

## su_msg_send_to()

int su_msg_send_to | ( | su_msg_r | rmsg,
|  | su_task_r const | to_task,
|  | su_msg_f | wakeup )

Send message to the to_task and mark from_task as sender.

Since
  New in 1.12.8

## su_msg_to()

su_task_r su_msg_to | ( | su_msg_cr | rmsg | ) |

Get destination task.

The function `su_msg_from` returns the task handle belonging to the recipient of the message.

If the message handle contains NULL the function `su_msg_to` returns NULL.

Parameters

  rmsg | message handle

Returns
  The task handle of the recipient is returned.

## su_port_prefer()

void su_port_prefer | ( | su_port_create_f * | create,
|  | su_clone_start_f * | start )

Explicitly set the preferred su_port_t implementation.

See also
  su_epoll_port_create(), su_poll_port_create(), su_select_port_create()

## su_root_break()

void su_root_break | ( | su_root_t * | self | ) |

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.

Parameters

  self | pointer to root object

## su_root_clone()

su_root_t * su_root_clone | ( | su_root_t * | self,
|  | su_root_magic_t * | magic )

Create a a new root object sharing port/thread with existing one.

Allocate and initialize the instance of su_root_t.

Parameters

  self | pointer to a root object.
  magic | pointer to user data

Returns
  A pointer to allocated su_root_t instance, NULL on error.

Since
  New in 1.12.11

## su_root_create()

su_root_t * su_root_create | ( | su_root_magic_t * | magic | ) |

Create a reactor object.

Allocate and initialize the instance of su_root_t.

Parameters

  magic | pointer to user data

Returns
  A pointer to allocated su_root_t instance, NULL on error.

## su_root_deregister()

int su_root_deregister | ( | su_root_t * | self,
|  | int | index )

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.

Parameters

  self | pointer to root object
  index | registration index

Returns
  Index of the wait object, or -1 upon an error.

## su_root_destroy()

void su_root_destroy | ( | su_root_t * | self | ) |

Destroy a root object.

Stop and free an instance of su_root_t

Parameters

  self | pointer to a root object.

## su_root_eventmask()

int su_root_eventmask | ( | su_root_t * | self,
|  | int | index,
|  | int | socket,
|  | int | events )

Set mask for a registered event.

The function su_root_eventmask() sets the mask describing events that can signal the registered callback.

Parameters

  self | pointer to root object
  index | registration index
  socket | socket
  events | new event mask

Return values

  0 | when successful,
  -1 | upon an error.

## su_root_get_max_defer()

su_duration_t su_root_get_max_defer | ( | su_root_t const * | self | ) |

Get maximum defer time.

The deferrable timers can be deferred until the task is otherwise activated, however, they are deferred no longer than the maximum defer time. The maximum defer time is 15 seconds by default.

Parameters

  self | pointer to root object

Returns
  Maximum defer time in milliseconds

Since
  New in 1.12.7

## su_root_has_thread()

int su_root_has_thread | ( | su_root_t * | root | ) |

Check if a thread has obtained the root.

Parameters

  root | a pointer to root object

Return values

  2 | if current thread has obtained the root
  1 | if an another thread has obtained the root
  0 | if no thread has obtained the root
  -1 | upon an error

Since
  New in 1.12.7

## su_root_magic()

su_root_magic_t * su_root_magic | ( | su_root_t * | self | ) |

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().

Parameters

  self | pointer to a root object

Returns
  A pointer to user data

## su_root_multishot()

int su_root_multishot | ( | su_root_t * | self,
|  | int | multishot )

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.

Parameters

  self | pointer to root object
  multishot | multishot mode (0 => disables, 1 => enables, -1 => query)

Return values

  0 | multishot mode is disabled
  1 | multishot mode is enabled
  -1 | an error occurred

## su_root_name()

char const * su_root_name | ( | su_root_t * | self | ) |

Get instance name.

Parameters

  self | pointer to a root object

Returns
  Instance name (e.g., "epoll", "devpoll", "select").

Since
  New in 1.12.6.

## su_root_obtain()

int su_root_obtain | ( | su_root_t * | root | ) |

Obtain the root port from other thread.

Parameters

  root | pointer to root object

Return values

  0 | if successful
  -1 | upon an error

Errors:

\n EFAULT

Since
  New in 1.12.7

## su_root_parent()

su_task_r su_root_parent | ( | su_root_t const * | self | ) |

Get parent task reference.

Retrieve the task reference of the parent task associated with the root object.

Parameters

  self | a pointer to a root object

Returns
  A reference to the parent task object.

## su_root_register()

int su_root_register | ( | su_root_t * | self,
|  | su_wait_t * | wait,
|  | su_wakeup_f | callback,
|  | su_wakeup_arg_t * | arg,
|  | int | priority )

Register a su_wait_t object.

The function su_root_register() registers a su_wait_t object. The wait object, a callback function and a argument are stored to the root object. The callback function is called, when the wait object is signaled.

Please note if identical wait objects are inserted, only first one is ever signalled.

Parameters

  self | pointer to root object
  wait | pointer to wait object
  callback | callback function pointer
  arg | argument given to callback function when it is invoked
  priority | relative priority of the wait object (0 is normal, 1 important, 2 realtime)

Returns
  Nonzero index of the wait object, or -1 upon an error.

## su_root_release()

int su_root_release | ( | su_root_t * | root | ) |

Release the root port for other threads.

Since
  New in 1.12.7

## su_root_run()

void su_root_run | ( | su_root_t * | self | ) |

Run event and message loop.

The function su_root_run() runs the root main loop. The root loop waits for wait objects and the timers associated with the root object. When any wait object is signaled or timer is expired, it invokes the callbacks, and returns waiting.

This function returns when su_root_break() is called from a callback.

Parameters

  self | pointer to root object

## su_root_set_magic()

int su_root_set_magic | ( | su_root_t * | self,
|  | su_root_magic_t * | magic )

Set the context pointer.

Set the context pointer (magic) of a root object.

Parameters

  self | pointer to a root object
  magic | pointer to user data

Return values

  0 | when successful,
  -1 | upon error.

## su_root_set_max_defer()

int su_root_set_max_defer | ( | su_root_t * | self,
|  | su_duration_t | max_defer )

Set maximum defer time.

The deferrable timers can be deferred until the task is otherwise activated, however, they are deferred no longer than the maximum defer time. The maximum defer time determines also the maximum time during which task waits for events while running. The maximum defer time is 15 seconds by default.

Cloned tasks inherit the maximum defer time.

Parameters

  self | pointer to root object
  max_defer | maximum defer time in milliseconds

Return values

  0 | when successful
  -1 | upon an error

See also
  su_timer_deferrable()

Since
  New in 1.12.11

## su_root_sleep()

su_duration_t su_root_sleep | ( | su_root_t * | self,
|  | su_duration_t | duration )

Run event and message loop for given duration.

The function su_root_sleep() runs event loop for duration milliseconds. The event loop waits for wait objects and the timers associated with the root object. When any wait object is signaled, timer is expired, or message is received, it invokes the callbacks and returns waiting.

Parameters

  self | pointer to root object
  duration | milliseconds to run event loop

Return values

  milliseconds | until next timer expiration

## su_root_stamp64()

su_time64_t su_root_stamp64 | ( | su_root_t const * | self | ) |

Get cached timestamp.

Get cached monotonic timestamp from root. The advantage of using this function over su_stamp64() is that when processing multiple events, Sofia can cache result from a single call instead of repeatedly calling the system monotonic clock.

The returned time uses the system monotonic clock, if available.

Parameters

  self | pointer to root object

Returns
  Cached time in nanosecond resolution

Since
  Not yet released

## su_root_stamp64_offset()

su_dur64_t su_root_stamp64_offset | ( | su_root_t const * | self | ) |

Get cached offset between monotonic timestamps and UTC time.

Get cached offset in nanoseconds between UTC time and monotonic timestamps returned by su_stamp64() or su_root_stamp64().

Parameters

  self | pointer to root object

Returns
  Cached offset in nanosecond resolution

Since
  Not yet released

## su_root_step()

su_duration_t su_root_step | ( | su_root_t * | self,
|  | su_duration_t | tout )

Process events, timers and messages.

The function su_root_step() waits for wait objects and the timers associated with the root object. When any wait object is signaled or timer is expired, it invokes the callbacks.

This function returns when a callback has been invoked or tout milliseconds is elapsed.

Parameters

  self | pointer to root object
  tout | timeout in milliseconds

Returns
  Milliseconds to the next invocation of timer

Return values

  SU_WAIT_FOREVER | if there are no active timers or if there was an error

## su_root_task()

su_task_r su_root_task | ( | su_root_t const * | self | ) |

Get task reference.

Retrieve the task reference related with the root object.

Parameters

  self | a pointer to a root object

Returns
  A reference to the task object.

## su_root_threading()

int su_root_threading | ( | su_root_t * | self,
|  | int | enable )

Set threading option.

Controls whether su_clone_start() creates a new thread.

Parameters

  self | pointer to a root object
  enable | if true, enable threading, if false, disable threading

Returns
  True if threading is enabled.

## su_root_unregister()

int su_root_unregister | ( | su_root_t * | self,
|  | su_wait_t * | wait,
|  | su_wakeup_f | callback,
|  | su_wakeup_arg_t * | arg )

Unregister a su_wait_t object.

The function su_root_unregister() unregisters a su_wait_t object. The wait object, a callback function and a argument are removed from the root object.

Parameters

  self | pointer to root object
  wait | pointer to wait object
  callback | callback function pointer (may be NULL)
  arg | argument given to callback function when it is invoked (may be NULL)

Returns
  Nonzero index of the wait object, or -1 upon an error.

## su_root_yield()

int su_root_yield | ( | su_root_t * | self | ) |

Check wait events in callbacks that take lots of time.

This function does a 0 timeout poll() and runs wait objects

Parameters

  self | pointer to root object

## su_task_cmp()

int su_task_cmp | ( | su_task_r const | a,
|  | su_task_r const | b )

Compare two tasks with each other.

Parameters

  a | First task
  b | Second task

Return values

  negative | number, if a < b
  positive | number, if a > b
  0,if | a == b.

## su_task_copy()

void su_task_copy | ( | su_task_r | dst,
|  | su_task_r const | src )

Duplicates a task handle.

Parameters

  dst | destination task reference
  src | source task reference

## su_task_deferrable()

su_timer_queue_t * su_task_deferrable | ( | su_task_r const | task | ) |

Return the queue for deferrable timers associated with given task.

Parameters

  task | task handle

Returns
  A timer list of the task.

Since
  New in 1.12.11

## su_task_deinit()

void su_task_deinit | ( | su_task_r | task | ) |

Destroy a task handle.

Parameters

  task | task handle

## su_task_execute()

int su_task_execute | ( | su_task_r const | task,
|  | int(* | function )(void *),
|  | void * | arg,
|  | int * | return_value )

Execute the function by task thread.

Return values

  0 | if successful
  -1 | upon an error

## su_task_init()

su_task_r su_task_init | ( | su_task_r | task | ) |

Initialize a task handle with su_task_null.

Parameters

  task | task handle

Returns
  A reference to the initialized task handle.

## su_task_is_running()

int su_task_is_running | ( | su_task_r const | task | ) |

Tests if a task is running.

Parameters

  task | task handle

Return values

  true | (nonzero) if task is not stopped,
  zero | if it is null or stopped.

Note
  A task sharing thread with another task is considered stopped when ever the the main task is stopped.

## su_task_move()

void su_task_move | ( | su_task_r | dst,
|  | su_task_r | src )

Moves a task handle.

Parameters

  dst | destination task reference
  src | source task reference

## su_task_root()

su_root_t * su_task_root | ( | su_task_r const | self | ) |

Get root pointer attached to a task handle.

Parameters

  self | task handle

Returns
  A pointer to root object attached to the task handle, or NULL if no root object has been attached.

## su_task_timers()

su_timer_queue_t * su_task_timers | ( | su_task_r const | task | ) |

Return the timer list associated with given task.

Parameters

  task | task handle

Returns
  A timer list of the task.

## su_task_wakeup()

int su_task_wakeup | ( | su_task_r const | task | ) |

Wakeup a task.

Wake up a task. This function is mainly useful when using deferrable timers executed upon wakeup.

Parameters

  task | task handle

Return values

  0 | if succesful
  -1 | upon an error

Since
  New in 1.12.11

## su_timer_create()

su_timer_t * su_timer_create | ( | su_task_r const | task,
|  | su_duration_t | msec )

Create a timer.

Allocate and initialize an instance of su_timer_t.

Parameters

  task | a task for root object with which the timer will be associated
  msec | the default duration of the timer in milliseconds

Returns
  A pointer to allocated timer instance, NULL on error.

## su_timer_deferrable()

int su_timer_deferrable | ( | su_timer_t * | t,
|  | int | value )

Change timer as deferrable (or as undeferrable).

A deferrable timer is executed after the given timeout, however, the task tries to avoid being woken up only because the timeout. Deferable timers have their own queue and timers there are ignored when calculating the timeout for epoll()/select()/whatever unless the timeout would exceed the maximum defer time. The maximum defer time is 15 seconds by default, but it can be modified by su_root_set_max_defer().

Parameters

  t | pointer to the timer
  value | make timer deferrable if true, undeferrable if false

Returns
  0 if succesful, -1 upon an error

See also
  su_root_set_max_defer()

Since
  New in 1.12.7

## su_timer_destroy()

void su_timer_destroy | ( | su_timer_t * | t | ) |

Destroy a timer.

Deinitialize and free an instance of su_timer_t.

Parameters

  t | pointer to the timer object

## su_timer_is_set()

int su_timer_is_set | ( | su_timer_t const * | t | ) |

Check if the timer has been set.

Parameters

  t | pointer to a timer object

Returns
  Nonzero if set, zero if reset.

Since
  New in 1.12.11

## su_timer_latest()

su_time_t su_timer_latest | ( | su_timer_t const * | t | ) |

Return when the timer has been last expired.

Parameters

  t | pointer to a timer object

Returns
  Timestamp (as returned by su_time()).

Note
  If the timer is running (set with su_timer_run()), the returned timestamp not the actual time but it is rather calculated from the initial timestamp.

Since
  New in 1.12.11

## su_timer_reset()

int su_timer_reset | ( | su_timer_t * | t | ) |

Reset the timer.

Resets (stops) the given timer.

Parameters

  t | pointer to the timer object

Returns
  0 if successful, -1 otherwise.

## su_timer_root()

su_root_t * su_timer_root | ( | su_timer_t const * | t | ) |

Get the root object owning the timer.

Return pointer to the root object owning the timer.

Parameters

  t | pointer to the timer

Returns
  Pointer to the root object.

## su_timer_run()

int su_timer_run | ( | su_timer_t * | t,
|  | su_timer_f | wakeup,
|  | su_timer_arg_t * | arg )

Set the timer for regular intervals.

Run the given timer continuously, call wakeup function repeately in the default interval. If a wakeup call is missed, try to make it up (in other words, this kind of timer fails miserably if time is adjusted and it should really use /proc/uptime instead of gettimeofday()).

While a continously running timer is active it must not be set using su_timer_set() or su_timer_set_at().

The timer must have an non-zero default interval.

Parameters

  t | pointer to the timer object
  wakeup | pointer to the wakeup function
  arg | argument given to the wakeup function

Returns
  0 if successful, -1 otherwise.

## su_timer_set()

int su_timer_set | ( | su_timer_t * | t,
|  | su_timer_f | wakeup,
|  | su_timer_arg_t * | arg )

Set the timer for the default interval.

Sets (starts) the given timer to expire after the default duration.

The timer must have an default duration.

Parameters

  t | pointer to the timer object
  wakeup | pointer to the wakeup function
  arg | argument given to the wakeup function

Returns
  0 if successful, -1 otherwise.

## su_timer_set_for_ever()

int su_timer_set_for_ever | ( | su_timer_t * | t,
|  | su_timer_f | wakeup,
|  | su_timer_arg_t * | arg )

Set the timer for regular intervals.

Run the given timer continuously, call wakeup function repeately in the default interval. While a continously running timer is active it must not be set using su_timer_set() or su_timer_set_at(). Unlike su_timer_run(), set for ever timer does not try to catchup missed callbacks.

The timer must have an non-zero default interval.

Parameters

  t | pointer to the timer object
  wakeup | pointer to the wakeup function
  arg | argument given to the wakeup function

Returns
  0 if successful, -1 otherwise.

## su_timer_set_interval()

int su_timer_set_interval | ( | su_timer_t * | t,
|  | su_timer_f | wakeup,
|  | su_timer_arg_t * | arg,
|  | su_duration_t | interval )

Set the timer for the given interval.

Sets (starts) the given timer to expire after the specified duration.

Parameters

  t | pointer to the timer object
  wakeup | pointer to the wakeup function
  arg | argument given to the wakeup function
  interval | duration in milliseconds before timer wakeup is called

Returns
  0 if successful, -1 otherwise.

## su_wait()

int su_wait | ( | su_wait_t | waits[],
|  | unsigned | n,
|  | su_duration_t | timeout )

Wait for multiple events.

The function su_wait() blocks until an event specified by wait objects in wait array. If timeout is not SU_WAIT_FOREVER, a timeout occurs after timeout milliseconds.

In Unix, this is `poll()` or `select()`.

In Windows, this is `WSAWaitForMultipleEvents()`.

Parameters

  waits | array of wait objects
  n | number of wait objects in array waits
  timeout | timeout in milliseconds

Return values

  Index | of the signaled wait object, if any,
  SU_WAIT_TIMEOUT | if timeout occurred, or
  -1 | upon an error.

## su_wait_create()

int su_wait_create | ( | su_wait_t * | newwait,
|  | su_socket_t | socket,
|  | int | events )

Create a wait object.

The function su_wait_create() creates a new su_wait_t object for an socket, with given events. The new wait object is assigned to the newwait parameter.

There can be only one wait object per socket. (This is a limitation or feature of WinSock interface; the limitation is not enforced on other platforms).

As a side-effect the socket is put into non-blocking mode when wait object is created.

Parameters

  newwait | the newly created wait object (output)
  socket | socket
  events | mask for events that can signal this wait object

Return values

  0 | if the call was successful,
  -1 | upon an error.

## su_wait_destroy()

int su_wait_destroy | ( | su_wait_t * | waitobj | ) |

Destroy a wait object.

The function su_wait_destroy() destroys a su_wait_t object.

Parameters

  waitobj | pointer to wait object

Return values

  0 | when successful,
  -1 | upon an error.

## su_wait_events()

int su_wait_events | ( | su_wait_t * | waitobj,
|  | su_socket_t | s )

Get events.

The function su_wait_events() returns an mask describing events occurred.

Parameters

  waitobj | pointer to wait object
  s | socket

Returns
  Binary mask describing the events.

## su_wait_init()

void su_wait_init | ( | su_wait_t | dst[1] | ) |

Initialize a wait object.

The function su_wait_init initializes a memory area of a su_wait_t object.

## su_wait_mask()

int su_wait_mask | ( | su_wait_t * | waitobj,
|  | su_socket_t | s,
|  | int | events )

Set event mask.

The function su_wait_mask() sets the mask describing events that can signal the wait object.

Parameters

  waitobj | pointer to wait object
  s | socket
  events | new event mask

Return values

  0 | when successful,
  -1 | upon an error.

Sofia-SIP 1.12.11devel - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.