Miscellaneous Thread Functions

[ Up: POSIX Threads ]
[ Previous: Streams and Fork ]

---

- Function: pthread_t pthread_self (void)

pthread_self returns the thread identifier for the calling thread.

- Function: int pthread_equal (pthread_t thread1, pthread_t thread2)

pthread_equal determines if two thread identifiers refer to the same thread.

A non-zero value is returned if thread1 and thread2 refer to the same thread. Otherwise, 0 is returned.

- Function: int pthread_detach (pthread_t th)

pthread_detach puts the thread th in the detached state. This guarantees that the memory resources consumed by th will be freed immediately when th terminates. However, this prevents other threads from synchronizing on the termination of th using pthread_join.

A thread can be created initially in the detached state, using the detachstate attribute to pthread_create. In contrast, pthread_detach applies to threads created in the joinable state, and which need to be put in the detached state later.

After pthread_detach completes, subsequent attempts to perform pthread_join on th will fail. If another thread is already joining the thread th at the time pthread_detach is called, pthread_detach does nothing and leaves th in the joinable state.

On success, 0 is returned. On error, one of the following codes is returned:

ESRCH

No thread could be found corresponding to that specified by th

EINVAL

The thread th is already in the detached state

- Function: void pthread_kill_other_threads_np (void)

pthread_kill_other_threads_np is a non-portable LinuxThreads extension. It causes all threads in the program to terminate immediately, except the calling thread which proceeds normally. It is intended to be called just before a thread calls one of the exec functions, e.g. execve.

Termination of the other threads is not performed through pthread_cancel and completely bypasses the cancellation mechanism. Hence, the current settings for cancellation state and cancellation type are ignored, and the cleanup handlers are not executed in the terminated threads.

According to POSIX 1003.1c, a successful exec* in one of the threads should automatically terminate all other threads in the program. This behavior is not yet implemented in LinuxThreads. Calling pthread_kill_other_threads_np before exec* achieves much of the same behavior, except that if exec* ultimately fails, then all other threads are already killed.

- Function: int pthread_once (pthread_once_t *once_control, void (*init_routine) (void))

The purpose of pthread_once is to ensure that a piece of initialization code is executed at most once. The once_control argument points to a static or extern variable statically initialized to PTHREAD_ONCE_INIT.

The first time pthread_once is called with a given once_control argument, it calls init_routine with no argument and changes the value of the once_control variable to record that initialization has been performed. Subsequent calls to pthread_once with the same once_control argument do nothing.

If a thread is cancelled while executing init_routine the state of the once_control variable is reset so that a future call to pthread_once will call the routine again.

If the process forks while one or more threads are executing pthread_once initialization routines, the states of their respective once_control variables will appear to be reset in the child process so that if the child calls pthread_once, the routines will be executed.

pthread_once always returns 0.

- Function: int pthread_setschedparam (pthread_t target_thread, int policy, const struct sched_param *param)

pthread_setschedparam sets the scheduling parameters for the thread target_thread as indicated by policy and param. policy can be either SCHED_OTHER (regular, non-realtime scheduling), SCHED_RR (realtime, round-robin) or SCHED_FIFO (realtime, first-in first-out). param specifies the scheduling priority for the two realtime policies. See sched_setpolicy for more information on scheduling policies.

The realtime scheduling policies SCHED_RR and SCHED_FIFO are available only to processes with superuser privileges.

On success, pthread_setschedparam returns 0. On error it returns one of the following codes:

EINVAL

policy is not one of SCHED_OTHER, SCHED_RR, SCHED_FIFO, or the priority value specified by param is not valid for the specified policy

EPERM

Realtime scheduling was requested but the calling process does not have sufficient privileges.

ESRCH

The target_thread is invalid or has already terminated

EFAULT

param points outside the process memory space

- Function: int pthread_getschedparam (pthread_t target_thread, int *policy, struct sched_param *param)

pthread_getschedparam retrieves the scheduling policy and scheduling parameters for the thread target_thread and stores them in the locations pointed to by policy and param, respectively.

pthread_getschedparam returns 0 on success, or one of the following error codes on failure:

ESRCH

The target_thread is invalid or has already terminated.

EFAULT

policy or param point outside the process memory space.

- Function: int pthread_setconcurrency (int level)

pthread_setconcurrency is unused in LinuxThreads due to the lack of a mapping of user threads to kernel threads. It exists for source compatibility. It does store the value level so that it can be returned by a subsequent call to pthread_getconcurrency. It takes no other action however.

- Function: int pthread_getconcurrency ()

pthread_getconcurrency is unused in LinuxThreads due to the lack of a mapping of user threads to kernel threads. It exists for source compatibility. However, it will return the value that was set by the last call to pthread_setconcurrency.