unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

LWP_CREATE(3L)                                                  LWP_CREATE(3L)



NAME
       lwp_create, lwp_destroy, SAMETHREAD, pod_setexit, pod_getexit, pod_exit
       - LWP thread creation and destruction primitives

SYNOPSIS
       #include <&lt;lwp/lwp.h>&gt;
       #include <&lt;lwp/stackdep.h>&gt;

       int lwp_create(tid, func, prio, flags, stack, nargs, arg1, ..., argn)
       thread_t *tid;
       void (*func)();
       int prio;
       int flags;
       stkalign_t *stack;
       int nargs;
       int arg1, ..., argn;

       int lwp_destroy(tid)
       thread_t tid;

       void pod_setexit(status)
       int status;

       int pod_getexit(status)
       int status;

       void pod_exit(status)
       int status

       SAMETHREAD(t1, t2)

DESCRIPTION
       lwp_create() creates a lightweight process which starts at address func
       and  has  stack segment stack.  If stack is NULL, the thread is created
       in a suspended state (see below) and no stack or pc  is  bound  to  the
       thread.   prio is the scheduling priority of the thread (higher priori-
       ties are favored by the scheduler).  The identity of the new thread  is
       filled in the reference parameter tid.  flags describes some options on
       the new thread.  LWPSUSPEND creates the thread in suspended state  (see
       lwp_yield(3L)).   LWPNOLASTRITES  will disable the LASTRITES agent mes-
       sage when the thread dies.  The default (0) is to create the thread  in
       running  state  with  LASTRITES reporting enabled.  LWPSERVER indicates
       that a thread is only viable  as  long  as  non-LWPSERVER  threads  are
       alive.   The  pod  will terminate if the only living threads are marked
       LWPSERVER and blocked on a lwp resource (for instance,  waiting  for  a
       message  to  be  sent).  nargs is the number (0 or more) of simple-type
       (int) arguments supplied to the thread.

       The first time a lwp primitive is used, the lwp  library  automatically
       converts  the caller (i.e., main) into a thread with the highest avail-
       able scheduling priority (see pod_getmaxpri(3L)).  The identity of this
       thread  can  be  retrieved  using  lwp_self (see lwp_status(3L)).  This
       thread has the normal SunOS stack given to any forked process.

       Scheduling is, by default, non-preemptive within a priority, and within
       a priority, threads enter the run queue on a FIFO basis (that is, when-
       ever a thread becomes eligible to run, it goes to the end  of  the  run
       queue  of  its  particular  priority).  Thus, a thread continues to run
       until it voluntarily relinquishes control or an event (including thread
       creation)  occurs  to enable a higher priority thread.  Some primitives
       may cause the current thread to block,  in  which  case  the  unblocked
       thread  with  the highest priority runs next.  When several threads are
       created with the same priority, they are queued for  execution  in  the
       order  of  creation.   This order may not be preserved as threads yield
       and block within a priority.  If an agent owned  by  a  thread  with  a
       higher priority is invoked, that thread will preempt the currently run-
       ning one.

       There is no concept of ancestry in threads: the creator of a thread has
       no  special  relation  to the thread it created.  When all threads have
       died, the pod terminates.

       lwp_destroy() is a way  to  explicitly  terminate  a  thread  or  agent
       (instead of having an executing thread "fall though", which also termi-
       nates the thread).  tid specifies the id of the thread or agent  to  be
       terminated.   If  tid  is SELF, the invoking thread is destroyed.  Upon
       termination, the resources (messages, monitor locks, agents)  owned  by
       the  thread  are  released,  in  some cases resulting in another thread
       being notified of the death of its peer (by having a blocking primitive
       become  unblocked  with  an  error indication).  A thread may terminate
       itself explicitly,  although  self-destruction  is  automatic  when  it
       returns from the procedure specified in the lwp_create() primitive.

       pod_setexit()  sets  the  exit  status  for  a pod.  This value will be
       returned to the parent process of the pod when the pod dies (default is
       0).  exit(3) terminates the current thread, using the argument supplied
       to exit to set the current value of the exit status.  on_exit(3) estab-
       lishes  an  action  that  will be taken when the entire pod terminates.
       pod_exit() is available to terminate the pod immediately with the final
       actions established by on_exit.  If you wish to terminate the pod imme-
       diately, pod_exit() or exit(2V) should be used.

       pod_getexit() returns the current value of the pod's exit status.

       SAMETHREAD() is a convenient predicate used to compare two threads  for
       equality.

RETURN VALUES
       lwp_create(), and lwp_destroy() return:

       0      on success.

       -1     on failure.

       pod_getexit() returns the current exit status of the pod.

ERRORS
       lwp_create() will fail if one or more of the following are true:

       LE_ILLPRIO          Illegal priority.

       LE_INVALIDARG       Too many arguments (> 512).

       LE_NOROOM           Unable to allocate memory for thread context.

       lwp_destroy() will fail if one or more of the following are true:

       LE_NONEXIST         Attempt  to destroy a thread or agent that does not
                           exist.

SEE ALSO
       exit(2V), exit(3), lwp_yield(3L), on_exit(3), pod_getmaxpri(3L)

WARNINGS
       Some special threads may be created silently by the lwp library.  These
       include  an  idle  thread that runs when no other activity is going on,
       and a reaper thread that frees stacks allocated by  lwp_newstk.   These
       special  threads will show up in status calls.  A pod will terminate if
       these special threads are the only ones extant.



                                21 January 1990                 LWP_CREATE(3L)