su_port.c File Reference


Detailed Description

OS-Independent Socket Syncronization Interface.

This looks like nth reincarnation of "reactor". It implements the poll/select/WaitForMultipleObjects and message passing functionality. This is virtual implementation:

Author:
Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>

Kai Vehmanen <kai.vehmanen@nokia-email.address.hidden>

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

#include "config.h"
#include "su_port.h"
#include <string.h>
#include <stdlib.h>

Include dependency graph for su_port.c:


Functions

su_port_tsu_default_port_create (void)
 Create the default su_port_t implementation.
void su_port_prefer (su_port_create_f *create, su_clone_start_f *start)
 Explicitly set the preferred su_port_t implementation.
su_port_tsu_port_create (void)
 Create the preferred su_port_t implementation.
char const * su_port_name (su_port_t const *port)
 Return name of the su_port_t instance.
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 a 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.

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 an exclusive lock on clone's private data.

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

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.

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

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

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.

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


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