CAC HAM VOI API THREAD-LUONG THUC THI.

NAME

pthread_join - wait for thread termination

SYNOPSIS

[THR] [Option Start] #include <pthread.h>

int pthread_join(pthread_t thread, void **value_ptr);

[Option End]

DESCRIPTION

The pthread_join() function shall suspend execution of the calling thread until the target thread
terminates, unless the target thread has already terminated. On return from a successful
pthread_join() call with a non-NULL value_ptr argument, the value passed to pthread_exit() by
the terminating thread shall be made available in the location referenced by value_ptr. When a
pthread_join() returns successfully, the target thread has been terminated. The results of
multiple simultaneous calls to pthread_join() specifying the same target thread are undefined. If
the thread calling pthread_join() is canceled, then the target thread shall not be detached.

It is unspecified whether a thread that has exited but remains unjoined counts against
{PTHREAD_THREADS_MAX}.

RETURN VALUE

If successful, the pthread_join() function shall return zero; otherwise, an error number shall be
returned to indicate the error.

ERRORS

The pthread_join() function shall fail if:

[ESRCH]

No thread could be found corresponding to that specified by the given thread ID.

The pthread_join() function may fail if:

[EDEADLK]

A deadlock was detected or the value of thread specifies the calling thread.

[EINVAL]

The value specified by thread does not refer to a joinable thread.

The pthread_join() function shall not return an error code of [EINTR].

The following sections are informative.

EXAMPLES

An example of thread creation and deletion follows:

typedef struct {
int *ar;
long n;
} subarray;

void * incer(void *arg)

{
long i;
for (i = 0; i < ((subarray *)arg)->n; i++)
((subarray *)arg)->ar[i]++;
}

int main(void)
{
int ar[1000000];
pthread_t th1, th2;
subarray sb1, sb2;
 sb1.ar = &ar[0];
sb1.n = 500000;
(void) pthread_create(&th1, NULL, incer, &sb1);
sb2.ar = &ar[500000];
sb2.n = 500000;
(void) pthread_create(&th2, NULL, incer, &sb2);
(void) pthread_join(th1, NULL);
(void) pthread_join(th2, NULL);
return 0;
}

APPLICATION USAGE

None.

RATIONALE

The pthread_join() function is a convenience that has proven useful in multi-threaded

applications. It is true that a programmer could simulate this function if it were not provided by
passing extra state as part of the argument to the start_routine(). The terminating thread would
set a flag to indicate termination and broadcast a condition that is part of that state; a joining
thread would wait on that condition variable. While such a technique would allow a thread to
wait on more complex conditions (for example, waiting for multiple threads to terminate),
waiting on individual thread termination is considered widely useful. Also, including the
pthread_join() function in no way precludes a programmer from coding such complex waits.
Thus, while not a primitive, including pthread_join() in this volume of IEEE Std 1003.1-2001 was
considered valuable.

The pthread_join() function provides a simple mechanism allowing an application to wait for a
thread to terminate. After the thread terminates, the application may then choose to clean up
resources that were used by the thread. For instance, after pthread_join() returns, any
application-provided stack storage could be reclaimed.

The pthread_join() or pthread_detach() function should eventually be called for every thread
that is created with the detachstate attribute set to PTHREAD_CREATE_JOINABLE so that storage
associated with the thread may be reclaimed.
The interaction between pthread_join() and cancellation is well-defined for the following
reasons:

The pthread_join() function, like all other non-async-cancel-safe functions, can only be called
with deferred cancelability type.

Cancellation cannot occur in the disabled cancelability state.

Thus, only the default cancelability state need be considered. As specified, either the
pthread_join() call is canceled, or it succeeds, but not both. The difference is obvious to the
application, since either a cancellation handler is run or pthread_join() returns. There are no race
conditions since pthread_join() was called in the deferred cancelability state.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_create(), wait(), the Base Definitions volume of IEEE Std 1003.1-2001, <pthread.h>

CHANGE HISTORY

First released in Issue 5. Included for alignment with the POSIX Threads Extension.

Issue 6

The pthread_join() function is marked as part of the Threads option.

IEEE Std 1003.1-2001/Cor 2-2004, XSH/TC2/D6/97 is applied, updating the ERRORS section so
that the [EINVAL] error is made optional and the words ``the implementation has detected'' are
removed from it.
//

NAME

pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock - lock and unlock a

mutex

SYNOPSIS

#include <pthread.h>

int pthread_mutex_lock(pthread_mutex_t *mutex);

The mutex object referenced by mutex shall be locked by calling pthread_mutex_lock(). If the
mutex is already locked, the calling thread shall block until the mutex becomes available. This
operation shall return with the mutex object referenced by mutex in the locked state with the
calling thread as its owner.

int pthread_mutex_trylock(pthread_mutex_t *mutex);

int pthread_mutex_unlock(pthread_mutex_t *mutex);

DESCRIPTION

The mutex object referenced by mutex is locked by calling pthread_mutex_lock(). If the mutex is
already locked, the calling thread blocks until the mutex becomes available. This operation
returns with the mutex object referenced by mutex in the locked state with the calling thread as
its owner.

If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection is not provided. Attempting

to relock the mutex causes deadlock. If a thread attempts to unlock a mutex that it has not
locked or a mutex which is unlocked, undefined behaviour results.

If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then error checking is provided. If a thread

attempts to relock a mutex that it has already locked, an error will be returned. If a thread
attempts to unlock a mutex that it has not locked or a mutex which is unlocked, an error will be
returned.

If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains the concept of a
lock count. When a thread successfully acquires a mutex for the first time, the lock count is set
to one. Every time a thread relocks this mutex, the lock count is incremented by one. Each time
the thread unlocks the mutex, the lock count is decremented by one. When the lock count
reaches zero, the mutex becomes available for other threads to acquire. If a thread attempts to
unlock a mutex that it has not locked or a mutex which is unlocked, an error will be returned.

If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively lock the mutex results
in undefined behaviour. Attempting to unlock the mutex if it was not locked by the calling thread
results in undefined behaviour. Attempting to unlock the mutex if it is not locked results in
undefined behaviour.

The function pthread_mutex_trylock() is identical to pthread_mutex_lock() except that if the

mutex object referenced by mutex is currently locked (by any thread, including the current
thread), the call returns immediately.

The pthread_mutex_unlock() function releases the mutex object referenced by mutex. The
manner in which a mutex is released is dependent upon the mutex's type attribute. If there are
threads blocked on the mutex object referenced by mutex when pthread_mutex_unlock() is
called, resulting in the mutex becoming available, the scheduling policy is used to determine
which thread shall acquire the mutex. (In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the
mutex becomes available when the count reaches zero and the calling thread no longer has any
locks on this mutex).

If a signal is delivered to a thread waiting for a mutex, upon return from the signal handler the
thread resumes waiting for the mutex as if it was not interrupted.

RETURN VALUE

If successful, the pthread_mutex_lock() and pthread_mutex_unlock() functions return zero.

Otherwise, an error number is returned to indicate the error.

The function pthread_mutex_trylock() returns zero if a lock on the mutex object referenced by
mutex is acquired. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_mutex_lock() and pthread_mutex_trylock() functions will fail if:

[EINVAL]

The mutex was created with the protocol attribute having the value PTHREAD_PRIO_PROTECT
and the calling thread's priority is higher than the mutex's current priority ceiling.

The pthread_mutex_trylock() function will fail if:

[EBUSY]

The mutex could not be acquired because it was already locked.

The pthread_mutex_lock(), pthread_mutex_trylock() and pthread_mutex_unlock() functions

may fail if:

[EINVAL]

The value specified by mutex does not refer to an initialised mutex object.

[EAGAIN]

The mutex could not be acquired because the maximum number of recursive locks for mutex has
been exceeded.

The pthread_mutex_lock() function may fail if:

[EDEADLK]

The current thread already owns the mutex.

The pthread_mutex_unlock() function may fail if:

[EPERM]

The current thread does not own the mutex.

These functions will not return an error code of [EINTR].

EXAMPLES

None.
APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_mutex_init(), pthread_mutex_destroy(), <pthread.h>.

DERIVATION

Derived from the POSIX Threads Extension (1003.1c-1995)

//

NAME

pthread_mutex_init, pthread_mutex_destroy - initialise or destroy a mutex

SYNOPSIS

#include <pthread.h>

int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t *attr);

int pthread_mutex_destroy(pthread_mutex_t *mutex);

pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;

DESCRIPTION

The pthread_mutex_init() function initialises the mutex referenced by mutex with attributes
specified by attr. If attr is NULL, the default mutex attributes are used; the effect is the same as
passing the address of a default mutex attributes object. Upon successful initialisation, the state
of the mutex becomes initialised and unlocked.

Attempting to initialise an already initialised mutex results in undefined behaviour.

The pthread_mutex_destroy() function destroys the mutex object referenced by mutex; the
mutex object becomes, in effect, uninitialised. An implementation may cause
pthread_mutex_destroy() to set the object referenced by mutex to an invalid value. A destroyed
mutex object can be re-initialised using pthread_mutex_init(); the results of otherwise
referencing the object after it has been destroyed are undefined.

It is safe to destroy an initialised mutex that is unlocked. Attempting to destroy a locked mutex
results in undefined behaviour.

In cases where default mutex attributes are appropriate, the macro

PTHREAD_MUTEX_INITIALIZER can be used to initialise mutexes that are statically allocated. The
effect is equivalent to dynamic initialisation by a call to pthread_mutex_init() with parameter attr
specified as NULL, except that no error checks are performed.

RETURN VALUE

If successful, the pthread_mutex_init() and pthread_mutex_destroy() functions return zero.

Otherwise, an error number is returned to indicate the error. The [EBUSY] and [EINVAL] error
checks, if implemented, act as if they were performed immediately at the beginning of
processing for the function and cause an error return prior to modifying the state of the mutex
specified by mutex.

ERRORS

The pthread_mutex_init() function will fail if:

[EAGAIN]

The system lacked the necessary resources (other than memory) to initialise another mutex.

[ENOMEM]

Insufficient memory exists to initialise the mutex.

[EPERM]

The caller does not have the privilege to perform the operation.

The pthread_mutex_init() function may fail if:

[EBUSY]

The implementation has detected an attempt to re-initialise the object referenced by mutex, a
previously initialised, but not yet destroyed, mutex.

[EINVAL]

The value specified by attr is invalid.

The pthread_mutex_destroy() function may fail if:

[EBUSY]

The implementation has detected an attempt to destroy the object referenced by mutex while it
is locked or referenced (for example, while being used in a pthread_cond_wait() or
pthread_cond_timedwait()) by another thread.

[EINVAL]

The value specified by mutex is invalid.

These functions will not return an error code of [EINTR].

EXAMPLES

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_mutex_getprioceiling(), pthread_mutex_lock(), pthread_mutex_unlock(),

pthread_mutex_setprioceiling(), pthread_mutex_trylock(), pthread_mutexattr_getpshared(),
pthread_mutexattr_setpshared(), <pthread.h>.

DERIVATION

Derived from the POSIX Threads Extension (1003.1c-1995)