PTL Original APIs
Note: All information in this page is out-of-date. Modern operating systems have multi-threading function so PTL is no longer useful.
PTL - Portable Thread Library
Top Page
Original APIs ->
Supported APIs
Debugger

   PTL Original APIs

This is the PTL original (i.e. non portable) API list.

If you use these APIs, it is recommended to surround them with #ifdef __PTL__. (__PTL__ is defined by <pthread.h>)

#ifdef __PTL__
...
#endif


int pthread_attr_setsuspended_np(pthread_attr_t *ATTR, int STATE)

int pthread_attr_getsuspended_np(const pthread_attr_t *ATTR, int *STATE_RETURN)

PTL has start_suspended attribute in the thread attributes (pthread_attr_t).

You can use pthread_attr_setsuspende_np() to set start_suspended attribute. STATE is one of PTHREAD_CREATE_NOT_SUSPENDED_NP(default) or PTHREAD_CREATE_SUSPENDED_NP.

If you create a thread with thread attribute PTHREAD_CREATE_SUSPENDED_NP,the created thread is initially suspended. You can use pthread_resume_np() to resume it.



int pthread_first_np(pthread_once_t *ONCE)

void pthread_first_done_np(pthread_once_t *ONCE)

These are similar to pthread_once(). These functions help executing a code fragment in a function only once. This is useful to initialize static variables in a function.

These functions can be used as follows.

foo()
{
    static pthread_once_t once = PTHREAD_ONCE_INIT;
    static int need_initialized;
    if (pthread_first_np(&once)) {
        need_initialized = appropriate_value();	/* Initialize */
            :
            :
        pthread_first_done_np(&once);
    }
    ....
}

pthread_first_np() returns 1 on the first time, and returns 0 on subsequent calls. pthread_first_done_np() declares that execution of the initialization code is done. If other thread calls pthread_first_np() before the first thread calls pthread_first_done_np(), the other thread is blocked until the first thread calls pthread_first_done_np().



int pthread_cleanup_pop_f_np(int)

int pthread_cleanup_push_f_np(void(*)(void*), void*)

These functions are function version of pthread_cleanup_push and pthread_cleanup_pop. The difference is you can use these _f_np functions in any place. You can pop a cleanup handler with pthread_cleanup_pop_f_np() pushed by pthread_cleanup_push().

Since PTL's pthread_cleanup_push/pop are implemented as macros, pthread_cleanup_push/pop must be used carefully to satisfy its lexical scope restriction.



int pthread_suspend_np(pthread_t THREAD)

int pthread_resume_np(pthread_t THREAD)

PTL can suspend and resume a thread. Use with care to avoid dead locks.



int pthread_set_exit_status_np(int EXITCODE)

This functions sets process's exit code, that is used when the last thread in the process exited with pthread_exit(). In POSIX standard, it is always 0 in this case.



int pthread_setname_np(pthread_t THREAD, const char *NAME)
int pthread_getname_np(pthread_t THREAD, char **NAME_RETURN)
int pthread_mutex_setname_np(pthread_mutex_t *MUTEX, const char *NAME)
int pthread_mutex_getname_np(pthread_mutex_t *MUTEX, char **NAME_RETURN)
int pthread_cond_setname_np(pthread_cond_t *COND, const char *NAME)
int pthread_cond_getname_np(pthread_cond_t *COND, char **NAME_RETURN)

You can set name to threads, mutexes, and condition variables. Names are used by PDB (PTL debugger) to display these objects symbolically. These given NAME are copied internally so you can destroy/modify the NAME after calling these setname functions.

These getname functions set the NAME_RETURN to these internally allocated name. You should not modify them.



int pthread_mutex_waiters_np(pthread_mutex_t *MUTEX)
int pthread_cond_waiters_np(pthread_cond_t *COND)

These functions returns # of waiters in a mutex or a condition variable. Only the thread that owns the mutex can get the correct value.



int pthread_alloc_stack_cache_np(pthread_attr_t *ATTR, int NUM)

This function pre-allocates # of stacks that satisfy the attribute ATTR. Allocated stacks are used by subsequent pthread_create() calls. This makes thread creation fast.



void pthread_poll_interval_np(const struct timespec *POLL, struct timespec *OPOLL)

In the case that some threads are waiting on I/O operations (such as read(), write(), msgrcv(), msgsnd(), semop()...) and also there are busy threads, PTL periodically polls their waiting descriptors (or message queue, semaphores, ...). Initial polling interval is 100msec.

This function changes this polling interval.



unsigned int pthread_alarm_np(unsigned int ALARMTIME)

PTL's alarm() sets the per process alarm timer as required by POSIX standard. With this function, you can set a per thread alarm timer. When a per thread alarm timer expires, SIGALRM is sent to the thread, not to the process.



unsigned int pthread_ualarm_np(unsigned int SEC, unsigned int USEC)

This functions is similar to pthread_alarm_np(), but can specify alarm timer value in micro sec resolution.



void pthread_debug_printf_np(const char *, ...)

This function prints a formatted message to stdout atomically (i.e. without any context switching).



void pthread_debug_pdb_np(const char *, ...)

This function adds a formatted message into the PTL internal ring buffer. This ring buffer can be shown by PDB's `dmesg' command. And while you are using PDB, the message is displayed to your debugging terminal.



int pthread_attr_setstackprop_np(pthread_attr_t*, int)
int pthread_attr_getstackprop_np(const pthread_attr_t*, int*)
int pthread_log_np()
int pthread_stack_expansion_np

Not documented yet.