lwp_yield, lwp_suspend, lwp_resume, lwp_join, lwp_setpri, lwp_resched, lwp_sleep - control LWP scheduling

---

SYNOPSIS

#include <lwp/lwp.h>

int lwp_yield(tid)
thread_t tid;

int lwp_sleep(timeout)
struct timeval *timeout;

int lwp_resched(prio)
int prio;

int lwp_setpri(tid, prio)
thread_t tid;
int prio;

int lwp_suspend(tid)
thread_t tid;

int lwp_resume(tid)
thread_t tid;

int lwp_join(tid)
thread_t tid;

DESCRIPTION

lwp_yield() allows the currently running thread to voluntarily relinquish control to another thread with the same scheduling priority. If tid is SELF, the next thread in the same priority queue of the yielding thread will run and the current thread will go the end of the scheduling queue. Otherwise, it is the ID of the thread to run next, and the current thread will take second place in the scheduling queue.

lwp_sleep() blocks the thread executing this primitive for at least the time specified by timeout.

Scheduling of threads is, by default, preemptive (higher priorities preempt lower ones) across priorities and non-preemptive within a priority. lwp_resched() moves the front thread for a given priority to the end of the scheduling queue. Thus, to achieve a preemptive round-robin scheduling discipline, a high priority thread can periodically wake up and shuffle the queue of threads at a lower priority. lwp_resched() does not affect threads which are blocked. If the priority of the rescheduled thread is the same as that of the caller, the effect is the same as lwp_yield().

lwp_setpri() is used to alter (raise or lower) the scheduling priority of the specified thread. If tid is SELF, the priority of the invoking thread is set. Note: if the priority of the affected thread becomes greater than that of the caller and the affected thread is not blocked, the caller will not run next. lwp_setpri() can be used on either blocked or unblocked threads.

lwp_join() blocks the thread issuing the join until the thread tid terminates. More than one thread may join tid.

lwp_suspend() makes the specified thread ineligible to run. If tid is SELF, the caller is itself suspended. lwp_resume() undoes the effect of lwp_suspend(). If a blocked thread is suspended, it will not run until it has been unblocked as well as explicitly made eligible to run using lwp_resume(). By suspending a thread, one can safely examine it without worrying that its execution-time state will change.

NOTES

RETURN VALUES

lwp_yield(), lwp_sleep(), lwp_resched(), lwp_join(), lwp_suspend() and lwp_resume() return:

0

on success.

-1

on failure.

lwp_setpri() returns the previous priority on success. On failure, it returns -1.

ERRORS

lwp_yield() will fail if one or more of the following is true:

LE_ILLPRIO

Attempt to yield to thread with different priority.

LE_INVALIDARG

Attempt to yield to a blocked thread.

LE_NONEXIST

Attempt to yield to a non-existent thread.

lwp_sleep() will fail if one or more of the following is true:

LE_INVALIDARG

Illegal timeout specified.

lwp_resched() will fail if one or more of the following is true:

LE_ILLPRIO

The priority queue specified contains no threads to reschedule.

LE_INVALIDARG

Attempt to reschedule thread at priority greater than that of the caller.

lwp_setpri() will fail if one or more of the following is true:

LE_INVALIDARG

The priority specified is beyond the maximum available to the pod.

LE_NONEXIST

Attempt to set priority of a non-existent thread.

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

LE_NONEXIST

Attempt to join a thread that does not exist.

lwp_suspend() will fail if one or more of the following is true:

LE_NONEXIST

Attempt to suspend a non-existent thread.

lwp_resume() will fail if one or more of the following is true:

LE_NONEXIST

Attempt to resume a non-existent thread.

Created by unroff & hp-tools. © somebody (See intro for details). All Rights Reserved. Last modified 11/5/97