PTHREAD_CREATE(3) manual page

From b41f74438672dd682bc01ae818cb3da654f22c1e Mon Sep 17 00:00:00 2001 From: marha Date: Wed, 13 Feb 2013 10:41:10 +0100 Subject: Updated to latest CVS version of pthreads --- pthreads/manual/ChangeLog | 17 ++ pthreads/manual/cpu_set.html | 119 ++++++++++++ pthreads/manual/index.html | 318 +++++++++++++++++---------------- pthreads/manual/pthread_create.html | 206 +++++++++++---------- pthreads/manual/pthread_join.html | 271 ++++++++++++++++------------ pthreads/manual/sched_setaffinity.html | 143 +++++++++++++++ 6 files changed, 705 insertions(+), 369 deletions(-) create mode 100755 pthreads/manual/cpu_set.html create mode 100755 pthreads/manual/sched_setaffinity.html (limited to 'pthreads/manual') diff --git a/pthreads/manual/ChangeLog b/pthreads/manual/ChangeLog index 071b847ef..6b72f075d 100644 --- a/pthreads/manual/ChangeLog +++ b/pthreads/manual/ChangeLog @@ -1,3 +1,20 @@ +2012-10-04 Ross Johnson + + * pthread_join.html (pthread_tryjoin_np): Added description. + * index.html (pthread_tryjoin_np): Added link. + +2012-09-20 Ross Johnson + + * cpu_set.html: New manual page. + * pthread_create.html: Updated. + * index.html: Updated. + * sched_setaffinity.html: Fixed corrupted formatting. + +2012-08-19 Ross Johnson + + * pthread_join.html(pthread_timedjoin_np): Added. + * index.html(pthread_timedjoin_np): Added link. + 2011-03-26 Ross Johnson * pthread_nutex_init.html (robust mutexes): Added diff --git a/pthreads/manual/cpu_set.html b/pthreads/manual/cpu_set.html new file mode 100755 index 000000000..45c38ce4f --- /dev/null +++ b/pthreads/manual/cpu_set.html @@ -0,0 +1,119 @@ + + + + + PTHREAD_CREATE(3) manual page + + + + + + +

POSIX +Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

Operations on CPU affinity sets:

CPU_EQUAL - test equality of two sets

CPU_ZERO - clear all CPUs from set

CPU_SET - set a specified CPU in a set

CPU_CLR - unset a specified CPU in a set

CPU_ISSET - test if a specified CPU in a set is set

CPU_COUNT - return the number of CPUs currently set

CPU_AND - obtain the intersection of two sets

CPU_OR - obtain the union of two sets

CPU_XOR - obtain the mutually excluded set

Synopsis

#include <sched.h> +

int CPU_EQUAL(cpu_set_t * set1, +cpu_set_t * set2);

void CPU_ZERO(cpu_set_t * set);

void CPU_SET(int cpu, +cpu_set_t * set);

void CPU_CLR(int cpu, +cpu_set_t * set);

int CPU_ISSET(int cpu, +cpu_set_t * set);

int CPU_COUNT(cpu_set_t * set);

void CPU_AND(cpu_set_t * destset, +cpu_set_t * srcset1, +cpu_set_t * srcset2);

void CPU_OR(cpu_set_t * destset, +cpu_set_t * srcset1, +cpu_set_t * srcset2);

void CPU_XOR(cpu_set_t * destset, +cpu_set_t * srcset1, +cpu_set_t * srcset2);

Description

The cpu_set_t data structure represents a set of CPUs. CPU sets +are used by sched_setaffinity() +and pthread_setaffinity_np(), +etc.

The cpu_set_t data type is implemented as a bitset. However, the +data structure is considered opaque: all manipulation of CPU sets +should be done via the macros described in this page.

The following macros are provided to operate on the CPU set set:

CPU_ZERO Clears set, so that it contains no CPUs.

CPU_SET Add CPU cpu to set.

CPU_CLR Remove CPU cpu from set.

CPU_ISSET Test to see if CPU cpu is a member of set.

CPU_COUNT Return the number of CPUs in set.

Where a cpu argument is specified, it should not produce +side effects, since the above macros may evaluate the argument more +than once.

The first available CPU on the system corresponds to a cpu value +of 0, the next CPU corresponds to a cpu value of 1, and so on.

The following macros perform logical operations on CPU sets:

CPU_AND Store the intersection of the sets srcset1 +and srcset2 in destset (which may be one of the source +sets).

CPU_OR Store the union of the sets srcset1 and +srcset2 in destset (which may be one of the source +sets).

CPU_XOR Store the XOR of the sets srcset1 and +srcset2 in destset (which may be one of the source +sets). The XOR means the set of CPUs that are in either srcset1 or +srcset2, but not both.

CPU_EQUAL Test whether two CPU set contain exactly the +same CPUs.

Return Value

These macros either return a value consistent with the operation +of nothing.

Errors

These macros do not return an error status.

POSIX threads API -reference

pthread_attr_destroy

pthread_attr_getdetachstate

pthread_attr_getinheritsched

pthread_attr_getschedparam

pthread_attr_getschedpolicy

pthread_attr_getscope

pthread_attr_getstackaddr

pthread_attr_getstacksize

pthread_attr_init

pthread_attr_setdetachstate

pthread_attr_setinheritsched

pthread_attr_setschedparam

pthread_attr_setschedpolicy

pthread_attr_setscope

pthread_attr_setstackaddr

pthread_attr_setstacksize

pthread_barrierattr_destroy

pthread_barrierattr_getpshared

pthread_barrierattr_init

pthread_barrierattr_setpshared

pthread_barrier_destroy

pthread_barrier_init

pthread_barrier_wait

pthread_cancel

pthread_cleanup_pop

pthread_cleanup_push

pthread_condattr_destroy

pthread_condattr_getpshared

pthread_condattr_init

pthread_condattr_setpshared

pthread_cond_broadcast

pthread_cond_destroy

pthread_cond_init

pthread_cond_signal

pthread_cond_timedwait

pthread_cond_wait

pthread_getconcurrency

pthread_getschedparam

pthread_getunique_np

pthread_getspecific

pthread_join

pthread_key_create

pthread_key_delete

pthread_kill

pthread_mutexattr_destroy

pthread_mutexattr_getkind_np

pthread_mutexattr_getpshared

pthread_mutexattr_getrobust

pthread_mutexattr_gettype

pthread_mutexattr_init

pthread_mutexattr_setkind_np

pthread_mutexattr_setpshared

pthread_mutexattr_setrobust

pthread_mutexattr_settype

pthread_mutex_consistent

pthread_mutex_destroy

pthread_mutex_init

pthread_mutex_lock

pthread_mutex_timedlock

pthread_mutex_trylock

pthread_mutex_unlock

pthread_once

pthread_rwlockattr_destroy

pthread_rwlockattr_getpshared

pthread_rwlockattr_init

pthread_rwlockattr_setpshared

pthread_rwlock_destroy

pthread_rwlock_init

pthread_rwlock_rdlock

pthread_rwlock_timedrdlock

pthread_rwlock_timedwrlock

pthread_rwlock_tryrdlock

pthread_rwlock_trywrlock

pthread_rwlock_unlock

pthread_rwlock_wrlock

pthread_self

pthread_setcancelstate

pthread_setcanceltype

pthread_setconcurrency

pthread_setschedparam

pthread_setspecific

pthread_sigmask

pthread_spin_destroy

pthread_spin_init

pthread_spin_lock

pthread_spin_trylock

pthread_spin_unlock

pthread_testcancel

sched_get_priority_max

sched_get_priority_min

sched_getscheduler

sched_setscheduler

sem_close

sem_open

sem_post_multiple

sem_unlink

Non-portable -Pthreads-w32 routines

pthreadCancelableTimedWait

pthreadCancelableWait

pthread_delay_np

pthread_getw32threadhandle_np

pthread_num_processors_np

pthread_win32_test_features_np

pthread_timechange_handler_np

pthread_win32_process_attach_np

pthread_win32_process_detach_np

pthread_win32_thread_attach_np

pthread_win32_thread_detach_np

Other

Portability -issues

- + + + + + + + + + + + +

POSIX Threads for Windows – REFERENCE - +Pthreads-w32

POSIX +threads API reference
Miscellaneous +POSIX thread safe routines provided by Pthreads-w32
Non-portable +Pthreads-w32 routines
Other

POSIX threads API +reference

cpu_set

pthread_attr_destroy

pthread_attr_getdetachstate

pthread_attr_getinheritsched

pthread_attr_getschedparam

pthread_attr_getschedpolicy

pthread_attr_getscope

pthread_attr_getstackaddr

pthread_attr_getstacksize

pthread_attr_init

pthread_attr_setdetachstate

pthread_attr_setinheritsched

pthread_attr_setschedparam

pthread_attr_setschedpolicy

pthread_attr_setscope

pthread_attr_setstackaddr

pthread_attr_setstacksize

pthread_barrierattr_destroy

pthread_barrierattr_getpshared

pthread_barrierattr_init

pthread_barrierattr_setpshared

pthread_barrier_destroy

pthread_barrier_init

pthread_barrier_wait

pthread_cancel

pthread_cleanup_pop

pthread_cleanup_push

pthread_condattr_destroy

pthread_condattr_getpshared

pthread_condattr_init

pthread_condattr_setpshared

pthread_cond_broadcast

pthread_cond_destroy

pthread_cond_init

pthread_cond_signal

pthread_cond_timedwait

pthread_cond_wait

pthread_getconcurrency

pthread_getschedparam

pthread_getunique_np

pthread_getspecific

pthread_join

pthread_timedjoin_np

pthread_tryjoin_np

pthread_key_create

pthread_key_delete

pthread_kill

pthread_mutexattr_destroy

pthread_mutexattr_getkind_np

pthread_mutexattr_getpshared

pthread_mutexattr_getrobust

pthread_mutexattr_gettype

pthread_mutexattr_init

pthread_mutexattr_setkind_np

pthread_mutexattr_setpshared

pthread_mutexattr_setrobust

pthread_mutexattr_settype

pthread_mutex_consistent

pthread_mutex_destroy

pthread_mutex_init

pthread_mutex_lock

pthread_mutex_timedlock

pthread_mutex_trylock

pthread_mutex_unlock

pthread_once

pthread_rwlockattr_destroy

pthread_rwlockattr_getpshared

pthread_rwlockattr_init

pthread_rwlockattr_setpshared

pthread_rwlock_destroy

pthread_rwlock_init

pthread_rwlock_rdlock

pthread_rwlock_timedrdlock

pthread_rwlock_timedwrlock

pthread_rwlock_tryrdlock

pthread_rwlock_trywrlock

pthread_rwlock_unlock

pthread_rwlock_wrlock

pthread_self

pthread_setcancelstate

pthread_setcanceltype

pthread_setconcurrency

pthread_setschedparam

pthread_setspecific

pthread_sigmask

pthread_spin_destroy

pthread_spin_init

pthread_spin_lock

pthread_spin_trylock

pthread_spin_unlock

pthread_testcancel

sched_get_priority_max

sched_get_priority_min

sched_getaffinity

sched_getscheduler

sched_setaffinity

sched_setscheduler

sem_close

sem_open

sem_post_multiple

sem_unlink

Non-portable +Pthreads-w32 routines

pthreadCancelableTimedWait

pthreadCancelableWait

pthread_delay_np

pthread_getw32threadhandle_np

pthread_num_processors_np

pthread_win32_test_features_np

pthread_timechange_handler_np

pthread_timedjoin_np

pthread_win32_process_attach_np

pthread_win32_process_detach_np

pthread_win32_thread_attach_np

pthread_win32_thread_detach_np

Other

Portability +issues

+ \ No newline at end of file diff --git a/pthreads/manual/pthread_create.html b/pthreads/manual/pthread_create.html index d1ebbc3e1..5e75de49b 100644 --- a/pthreads/manual/pthread_create.html +++ b/pthreads/manual/pthread_create.html @@ -1,94 +1,112 @@ - - - - - PTHREAD_CREATE(3) manual page - - - - - - - -

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_create - create a new thread -

Synopsis

#include <pthread.h> -

int pthread_create(pthread_t * thread, -pthread_attr_t * attr, void * (*start_routine)(void -*), void * arg); -

Description

pthread_create creates a new thread of control that -executes concurrently with the calling thread. The new thread applies -the function start_routine passing it arg as first -argument. The new thread terminates either explicitly, by calling -pthread_exit(3) , or -implicitly, by returning from the start_routine function. The -latter case is equivalent to calling pthread_exit(3) -with the result returned by start_routine as exit code. -

The initial signal state of the new thread is inherited from it's -creating thread and there are no pending signals. Pthreads-w32 -does not yet implement signals.

The attr argument specifies thread attributes to be applied -to the new thread. See pthread_attr_init(3) -for a complete list of thread attributes. The attr argument -can also be NULL, in which case default attributes are used: -the created thread is joinable (not detached) and has default (non -real-time) scheduling policy. -

Return Value

On success, the identifier of the newly created thread is stored -in the location pointed by the thread argument, and a 0 is -returned. On error, a non-zero error code is returned. -

Errors

EAGAIN -

-Author

Xavier Leroy <Xavier.Leroy@inria.fr> -

Modified by Ross Johnson for use with Pthreads-w32.

Name

pthread_create - create a new thread +

Synopsis

#include <pthread.h> +

int pthread_create(pthread_t * thread, +pthread_attr_t * attr, void * (*start_routine)(void +*), void * arg); +

Description

pthread_create creates a new thread of control that +executes concurrently with the calling thread. The new thread applies +the function start_routine passing it arg as first +argument. The new thread terminates either explicitly, by calling +pthread_exit(3) , or +implicitly, by returning from the start_routine function. The +latter case is equivalent to calling pthread_exit(3) +with the result returned by start_routine as exit code. +

The initial signal state of the new thread is inherited from it's +creating thread and there are no pending signals. Pthreads-w32 +does not yet implement signals.

The initial CPU affinity of the new thread is inherited from it's +creating thread. A threads CPU affinity can be obtained through +pthread_getaffinity_np(3) +and may be changed through pthread_setaffinity_np(3). +Unless changed, all threads inherit the CPU affinity of the parent +process. See sched_getaffinity(3) +and sched_setaffinity(3).

The attr argument specifies thread attributes to be applied +to the new thread. See pthread_attr_init(3) +for a complete list of thread attributes. The attr argument +can also be NULL, in which case default attributes are used: +the created thread is joinable (not detached) and has default (non +real-time) scheduling policy. +

Return Value

On success, the identifier of the newly created thread is stored +in the location pointed by the thread argument, and a 0 is +returned. On error, a non-zero error code is returned. +

Errors

EAGAIN +

+Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Modified by Ross Johnson for use with Pthreads-w32.

Name

pthread_join - wait for termination of another thread -

Synopsis

#include <pthread.h> -

int pthread_join(pthread_t th, void -**thread_return); -

Description

pthread_join suspends the execution of the calling thread -until the thread identified by th terminates, either by -calling pthread_exit(3) or by -being cancelled. -

If thread_return is not NULL, the return value of th -is stored in the location pointed to by thread_return. The -return value of th is either the argument it gave to -pthread_exit(3) , or -PTHREAD_CANCELED if th was cancelled. -

The joined thread th must be in the joinable state: it must -not have been detached using pthread_detach(3) -or the PTHREAD_CREATE_DETACHED attribute to pthread_create(3) -. -

When a joinable thread terminates, its memory resources (thread -descriptor and stack) are not deallocated until another thread -performs pthread_join on it. Therefore, pthread_join -must be called once for each joinable thread created to avoid memory -leaks. -

At most one thread can wait for the termination of a given thread. -Calling pthread_join on a thread th on which another -thread is already waiting for termination returns an error. -

Cancellation

pthread_join is a cancellation point. If a thread is -cancelled while suspended in pthread_join, the thread -execution resumes immediately and the cancellation is executed -without waiting for the th thread to terminate. If -cancellation occurs during pthread_join, the th thread -remains not joined. -

Return Value

On success, the return value of th is stored in the -location pointed to by thread_return, and 0 is returned. On -error, a non-zero error code is returned. -

Errors

ESRCH -: - No thread could be found corresponding to that specified by th. -
- EINVAL -: - The th thread has been detached. -
- EINVAL -: - Another thread is already waiting on termination of th. -
- EDEADLK -: - The th argument refers to the calling thread. -

-Author

Xavier Leroy <Xavier.Leroy@inria.fr> -

Name

pthread_join - wait for termination of another thread

pthread_timedjoin_np - wait for termination of another thread with +a timeout +

pthread_tryjoin_np – join another thread without waiting

Synopsis

#include <pthread.h> +

int pthread_join(pthread_t th, void +**thread_return); +

int pthread_timedjoin_np(pthread_t th, void +**thread_return, const +struct timespec *abstime); +

int pthread_tryjoin_np(pthread_t th, void +**thread_return); +

Description

pthread_join suspends the execution of the calling thread +until the thread identified by th terminates, either by +calling pthread_exit(3) or by +being cancelled. +

If thread_return is not NULL, the return value of th +is stored in the location pointed to by thread_return. The +return value of th is either the argument it gave to +pthread_exit(3) , or +PTHREAD_CANCELED if th was cancelled. +

The joined thread th +must be in the joinable state: it must not have been detached using +pthread_detach(3) or the +PTHREAD_CREATE_DETACHED attribute to pthread_create(3) +. +

When a joinable thread terminates, its memory resources (thread +descriptor and stack) are not deallocated until another thread +performs pthread_join on it. Therefore, pthread_join +must be called once for each joinable thread created to avoid memory +leaks.

pthread_timedjoin_np is identical to pthread_join except +that it will return the error ETIMEDOUT if the target thread th +has not exited before abstime passes. If abstime is +NULL the function will wait forever and it's behaviour will therefore +be identical to pthread_join.

pthread_tryjoin_np is identical to pthread_join except that +it will return immediately with the error EBUSY if the target thread +th has not exited.

At most one thread can wait for the termination of a given thread. +Calling pthread_join on a thread th on which another +thread is already waiting for termination returns an error. +

Cancellation

pthread_join, pthread_tryjoin_np and +pthread_timedjoin_np are cancellation points. If a +thread is cancelled while suspended in either +function, the thread execution resumes immediately and the +cancellation is executed without waiting for the th thread to +terminate. If cancellation occurs during either function, the th +thread remains not joined. +

Return Value

On success, the return value of th is stored in the +location pointed to by thread_return, and 0 is returned. On +error, a non-zero error code is returned. +

Errors

ESRCH +: + No thread could be found corresponding to that specified by th. +
+ EINVAL +: + The th thread has been detached. +
+ EINVAL +: + Another thread is already waiting on termination of th. +
+ ETIMEDOUT +: + (pthread_timedjoin_np + only): abstime passed + before th could be + joined. +
+ EDEADLK +: + The th argument refers to the calling thread. +

+Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Modified by Ross Johnson for use with Pthreads-w32. +

Name

sched_setaffinity - set process CPU affinity

sched_getaffinity - get process CPU affinity

Synopsis

#include <sched.h> +

int sched_setaffinity(pid_t pid, +int cpusetsize, +const cpu_set_t *mask);

int sched_getaffinity(pid_t pid, +int cpusetsize, +cpu_set_t *mask);

Description

sched_setaffinity sets the CPU affinity mask of the process +whose ID is pid to the value specified by mask. If pid +is zero, then the calling process is used. The argument cpusetsize +is the length (in bytes) of the data pointed to by mask. +Normally this argument would be specified as sizeof(cpu_set_t).

If the process specified by pid is not currently running on +one of the CPUs specified in mask, then that process is +migrated to one of the CPUs specified in mask.

After a call to sched_setaffinity, the set of CPUs on which +the process will actually run is the intersection of the set +specified in the mask argument and the set of CPUs actually +present on the system.

sched_getaffinity writes the affinity mask of the process +whose ID is pid into the cpu_set_t structure pointed to by +mask. The cpusetsize argument specifies the size (in +bytes) of mask. If pid is zero, then the mask of the +calling process is returned.

Pthreads-w32 currently ignores the cpusetsize +parameter for either function because cpu_set_t is a direct typeset +to the Windows affinity vector type DWORD_PTR.

Windows may require that the requesting process have permission to +set its own CPU affinity or that of another process.

Return Value

On success, sched_setaffinity and sched_getaffinity +return 0. On error, -1 is returned, and errno is set +appropriately.

Errors

EFAULT
+ EINVAL
+ EAGAIN
+ EPERM
+ ESRCH +

+Application Usage

A process's CPU affinity mask determines the set of CPUs on which +it is eligible to run. On a multiprocessor system, setting the CPU +affinity mask can be used to obtain performance benefits. For +example, by dedicating one CPU to a particular process (i.e., setting +the affinity mask of that process to specify a single CPU, and +setting the affinity mask of all other processes to exclude that +CPU), it is possible to ensure maximum execution speed for that +process. Restricting a process to run on a single CPU also avoids the +performance cost caused by the cache invalidation that occurs when a +process ceases to execute on one CPU and then recommences execution +on a different CPU.

A CPU affinity mask is represented by the cpu_set_t structure, a +"CPU set", pointed to by mask. A set of macros for +manipulating CPU sets is described in cpu_set(3).

Copyright

Most of this is taken from the Linux manual page.

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Application + Usage
+
See + Also
+
Copyright
+

+

+ + \ No newline at end of file -- cgit v1.2.3

POSIX +Threads for Windows – REFERENCE - Pthreads-w32

+

POSIX Threads for Windows – REFERENCE - -Pthreads-w32

Table of Contents

POSIX Threads for Windows – REFERENCE - +Pthreads-w32

Table of Contents

POSIX Threads for Windows – REFERENCE - Pthreads-w32

-Author

POSIX Threads for Windows – REFERENCE - +Pthreads-w32

+Author

POSIX Threads for Windows – REFERENCE - Pthreads-w32

-Author

POSIX Threads for Windows – REFERENCE - +Pthreads-w32

+Author

POSIX +Threads for Windows – REFERENCE - Pthreads-w32

+Application Usage

+