su_root.c File Reference


Detailed Description

OS-independent synchronization interface.

#include "config.h"
#include <stdlib.h>
#include <assert.h>
#include <stdio.h>
#include <string.h>
#include <errno.h>
#include "sofia-sip/su.h"
#include <pthread.h>
#include "su_port.h"
#include "sofia-sip/su_alloc.h"

Include dependency graph for su_root.c:


Functions

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.
su_task_r su_task_new (su_task_r task, su_root_t *root, su_port_t *port)
 Create a new 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 a, su_task_r const b)
 Compare two tasks with each other.
int su_task_is_running (su_task_r const task)
 Tests if a task is running.
su_root_tsu_task_root (su_task_r const self)
 Get root pointer attached to a task handle.
su_timer_t ** su_task_timers (su_task_r const task)
 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 by task thread.
int su_timer_reset_all (su_timer_t **t0, su_task_r)
 Resets and frees all timers belonging to a task.
su_root_tsu_root_create (su_root_magic_t *magic)
 Create a reactor object.
su_root_tsu_root_create_with_port (su_root_magic_t *magic, su_port_t *port)
 Create a reactor object using given message port.
void su_root_destroy (su_root_t *self)
 Destroy a synchronization object.
int su_root_set_magic (su_root_t *self, su_root_magic_t *magic)
 Set the context pointer.
int su_root_threading (su_root_t *self, int enable)
 Set threading option.
su_root_magic_tsu_root_magic (su_root_t *self)
 Get context pointer.
_GSource * su_root_gsource (su_root_t *self)
 Get a GSource.
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.
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.
int su_root_deregister (su_root_t *self, int i)
 Remove a su_wait_t registration.
int su_root_eventmask (su_root_t *self, int index, int socket, int events)
 Set mask for a registered event.
int su_root_multishot (su_root_t *self, int multishot)
 Set multishot mode.
void su_root_run (su_root_t *self)
 Run event and message loop.
void su_root_break (su_root_t *self)
 Terminate event loop.
su_duration_t su_root_step (su_root_t *self, su_duration_t tout)
 Process events, timers and messages.
su_duration_t su_root_sleep (su_root_t *self, su_duration_t duration)
 Run event and message loop for given duration.
int su_root_yield (su_root_t *self)
 Check wait events in callbacks that take lots of time.
su_task_r su_root_task (su_root_t const *self)
 Get task reference.
su_task_r su_root_parent (su_root_t const *self)
 Get parent task reference.
int su_root_add_prepoll (su_root_t *root, su_prepoll_f *callback, su_prepoll_magic_t *magic)
 Add a pre-poll callback.
int su_root_remove_prepoll (su_root_t *root)
 Remove a pre-poll callback.
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.
su_task_r su_clone_task (su_clone_r clone)
 Get reference to clone task.
void su_clone_forget (su_clone_r rclone)
 Forget the clone.
void su_clone_stop (su_clone_r rclone)
 Stop the clone.
void su_clone_wait (su_root_t *root, su_clone_r rclone)
 Stop a clone and wait until it is has completed.
int su_clone_pause (su_clone_r rclone)
 Pause a clone.
int su_clone_resume (su_clone_r rclone)
 Resume a clone.
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.
int su_msg_report (su_msg_r msg, su_msg_f report)
 Add a delivery report function to a message.
int su_msg_reply (su_msg_r reply, su_msg_r const msg, su_msg_f wakeup, isize_t size)
 Allocates a reply message of given size.
void su_msg_delivery_report (su_msg_r msg)
 Send a delivery report.
void su_msg_save (su_msg_r save, su_msg_r msg)
 Save a message.
void su_msg_destroy (su_msg_r rmsg)
 Destroys an unsent message.
su_msg_arg_tsu_msg_data (su_msg_cr rmsg)
 Gets a pointer to the message data area.
isize_t su_msg_size (su_msg_cr rmsg)
 Get size of message data area.
su_task_r su_msg_from (su_msg_r const msg)
 Get sending task.
su_task_r su_msg_to (su_msg_r const msg)
 Get destination task.
void su_msg_remove_refs (su_msg_r const msg)
 Remove references to 'from' and 'to' tasks from a message.
int su_msg_send (su_msg_r rmsg)
 Send a message.

Variables

int su_root_size_hint
 Hint for number of registered fds in su_root.
su_task_r const su_task_null
 NULL task.

Function Documentation

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.

int su_clone_pause ( su_clone_r  rclone  ) 

Pause a clone.

Obtain a exclusive lock on clone's private data.

Return values:
0 if successful (and clone is paused)
-1 upon an error

int su_clone_resume ( su_clone_r  rclone  ) 

Resume a clone.

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

Return values:
0 if successful (and clone is resumed)
-1 upon an error

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.

The function su_clone_start() allocates and initializes a sub-task. Depending on the 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 (may be NULL if multi-threaded)
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.
See also:
su_root_threading(), su_clone_task(), su_clone_stop(), su_clone_wait(), su_clone_forget().

void su_clone_stop ( su_clone_r  rclone  ) 

Stop the clone.

Deprecated:
. Use su_clone_wait().

su_task_r su_clone_task ( su_clone_r  clone  ) 

Get reference to clone task.

Parameters:
clone Clone pointer
Returns:
A reference to the task structure of the clone.

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 message reached the clone.

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_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.

void su_msg_delivery_report ( su_msg_r  msg  ) 

Send a delivery report.

If the sender has attached a delivery report function to message with su_msg_report(), the message is returned to the message queue of the sending task. The sending task calls the delivery report function when it has received the message.

void su_msg_destroy ( su_msg_r  rmsg  ) 

Destroys an unsent message.

Parameters:
rmsg message handle.

su_task_r su_msg_from ( su_msg_r const  msg  ) 

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:
msg message handle
Returns:
The task handle of the sender is returned.

void su_msg_remove_refs ( su_msg_r const  msg  ) 

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

Parameters:
msg message handle

int su_msg_reply ( su_msg_r  reply,
su_msg_r const  msg,
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)
msg 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.

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

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_task_r su_msg_to ( su_msg_r const  msg  ) 

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:
msg message handle
Returns:
The task handle of the recipient is returned.

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_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_t* su_root_create_with_port ( su_root_magic_t magic,
su_port_t port 
)

Create a reactor object using given message port.

Allocate and initialize the instance of su_root_t.

Parameters:
magic pointer to user data
port pointer to a message port
Returns:
A pointer to allocated su_root_t instance, NULL on error.

int su_root_deregister ( su_root_t self,
int  i 
)

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
i registration index
Returns:
Index of the wait object, or -1 upon an error.

void su_root_destroy ( su_root_t self  ) 

Destroy a synchronization object.

Stop and free an instance of su_root_t

Parameters:
self pointer to a root object.

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_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

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_task_r su_root_parent ( su_root_t const *  self  ) 

Get parent task reference.

The function su_root_parent() is used to retrieve the task reference (PId) of the parent task.

Parameters:
self a pointer to a root object
Returns:
The function su_root_parent() returns a reference to the parent task object.

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.

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

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_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

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, or SU_WAIT_FOREVER if there are no active timers.

su_task_r su_root_task ( su_root_t const *  self  ) 

Get task reference.

The function su_root_task() is used to retrieve the task reference (PId) related with the root object.

Parameters:
self a pointer to a root object
Returns:
The function su_root_task() returns a reference to the task object.

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.

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.

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

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.

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

void su_task_deinit ( su_task_r  task  ) 

Destroy a task handle.

Parameters:
task task handle

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

Execute by task thread.

Return values:
0 if successful
-1 upon an error

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.

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.

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_r su_task_new ( su_task_r  task,
su_root_t root,
su_port_t port 
)

Create a new task handle.

Parameters:
task task reference
root pointer to root object
port pointer to port object
Returns:
New task handle.

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_timer_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. If there are no timers, it returns NULL.

int su_timer_reset_all ( su_timer_t **  timers,
su_task_r  task 
)

Resets and frees all timers belonging to a task.

The function su_timer_destroy_all() resets and frees all timers belonging to the specified task in the queue.

Parameters:
timers pointer to the timers
task task owning the timers
Returns:
Number of timers reset.


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