srv_spawn

Description

Allocate a service thread.

Syntax

CS_RETCODE srv_spawn(sppp, stacksize, funcp, 
                  argp, priority)

SRV_PROC            **sppp;
CS_INT                   stacksize;
CS_RETCODE        (*funcp)();
CS_VOID                *argp;
CS_INT                 priority;

Parameters

sppp: A pointer to a thread structure pointer. If the call is successful, the address of an internal thread structure is returned in sppp.

stacksize: The size of the stack; it must be at least SRV_C_MINSTACKSIZE. Specify SRV_DEFAULT_STACKSIZE to use the stack size set with srv_props(SRV_S_STACKSIZE).

funcp: A pointer to a function that is the entry point for the newly created thread. The thread begins by executing the routine located at funcp. The thread is freed when that routine returns or srv_termproc is called.

argp: A pointer that is passed to the routine in *funcp when the thread begins execution.

priority: An integer between SRV_C_LOWPRIORITY and SRV_C_MAXPRIORITY that indicates the base priority of the spawned thread. The default priority is SRV_C_DEFAULTPRI.

Returns

srv_spawn returns CS_SUCCEED if the thread is successfully spawned. This guarantees only that sufficient Open Server internal resources are available. It does not validate the correctness of the entry point routine or its argument. If the thread cannot be spawned, srv_spawn returns CS_FAIL.

**Table 3-133: Return values (srv_spawn)**
Returns	To indicate
CS_SUCCEED	The routine completed successfully.
CS_FAIL	The routine failed.

Examples

Example 1

#include    <stdio.h>

#include    <ospublic.h>

/*

** Local Prototype.

*/

CS_RETCODE       entryfunc PROTOTYPE((

CS_CHAR          *message

));

CS_RETCODE       ex_srv_spawn PROTOTYPE((

SRV_PROC         *spp,

CS_INT           stacksize,

CS_INT           priority

));

CS_RETCODE    entryfunc(message)

CS_CHAR       *message;

      printf(“Welcome to a new thread - %s!\n”, message);

      return(CS_SUCCEED);

/*

** EX_SRV_SPAWN

**

**    Example routine to allocate a service thread

**

** Arguments:

**    spp      A pointer to an internal thread control

 **             structure.

**    stacks   The desired thread stack size.

**    priority The desired thread scheduling priority.

**

** Returns:

**

**    CS_SUCCEED

**    CS_FAIL

*/

CS_RETCODE    ex_srv_spawn(spp, stacksize, priority)

SRV_PROC      *spp;

CS_INT        stacksize;

CS_INT        priority;

    CS_CHAR      msgarg[20];

    strcpy(msgarg, “come in”);

    return(srv_spawn(&spp, stacksize, entryfunc, msgarg,

              priority));

Usage

srv_spawn allocates a “service” thread—one that is neither event-driven nor associated with any client. The thread runs under the control of the scheduler.
Threads created by srv_spawn are called service threads because they often provide services required by the event-driven threads, such as accessing shared devices and data objects.
srv_spawn informs the Open Server about a new thread and makes the thread runnable. The thread does not begin execution immediately. The moment that it actually does start execution is determined by many factors, such as the priority of the spawned thread and the priorities of other runnable threads.
If you do not call srv_props to configure the stacksize with SRV_S_STACKSIZE, a new thread is created with the default stacksize. This default stacksize depends on the platform used. For native-threaded versions of Open Server, the default stacksize of underlying threads is used.
Code executed by multiple threads must be re-entrant.