pthread.pod

Linux下的中文输入法

None.

=head1 FUTURE DIRECTIONS

None.

=head1 SEE ALSO

I<pthread_cancel()>,
I<pthread_setcancelstate()>,
I<<pthread.h>>.

=head1 ______________________________________________________________________

=head1 NAME

B<pthread_cleanup_push,> B<pthread_cleanup_pop> - establish cancellation handlers

=head1 SYNOPSIS

#include <pthread.h>

void pthread_cleanup_push(void (*I<routine>)(void*), void *I<arg>);
void pthread_cleanup_pop(int I<execute>);

=head1 DESCRIPTION

The
I<pthread_cleanup_push()>
function pushes the specified cancellation cleanup handler
I<routine>
onto the calling thread's cancellation cleanup stack.
The cancellation cleanup handler is popped from the
cancellation cleanup stack and invoked with the argument
I<arg>
when: (a) the thread exits (that is, calls
I<pthread_exit()>),
(b) the thread acts upon a cancellation request, or
(c) the thread calls
I<pthread_cleanup_pop()>
with a non-zero
I<execute>
argument.

The
I<pthread_cleanup_pop()>
function removes the routine at the top of the calling thread's
cancellation cleanup stack and optionally invokes it (if
I<execute>
is non-zero).

These functions may be implemented as macros and will
appear as statements and in pairs within the same lexical scope (that is, the
I<pthread_cleanup_push()>
macro may be thought to expand to a token list whose first
token is
B<`{'>
with
I<pthread_cleanup_pop()>
expanding to a token list whose last token is the corresponding
B<`}'>.

The effect of calling
I<longjmp()>
or
I<siglongjmp()>
is undefined if there have been any calls to
I<pthread_cleanup_push()>
or
I<pthread_cleanup_pop()>
made without the matching call
since the jump buffer was filled.
The effect of calling
I<longjmp()>
or
I<siglongjmp()>
from inside a cancellation cleanup handler is also
undefined unless the jump buffer was also filled in the
cancellation cleanup handler.

=head1 RETURN VALUE

The
I<pthread_cleanup_push()>
and
I<pthread_cleanup_pop()>
functions return no value.

=head1 ERRORS

No errors are defined.

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

=head1 EXAMPLES

None.

=head1 APPLICATION USAGE

None.

=head1 FUTURE DIRECTIONS

None.

=head1 SEE ALSO

I<pthread_cancel()>,
I<pthread_setcancelstate()>,
I<<pthread.h>>.

=head1 ______________________________________________________________________

=head1 NAME

B<pthread_cond_signal,> B<pthread_cond_broadcast> - signal or broadcast a
condition

=head1 SYNOPSIS

#include <pthread.h>

int pthread_cond_signal(pthread_cond_t *I<cond>);
int pthread_cond_broadcast(pthread_cond_t *I<cond>);

=head1 DESCRIPTION

These two functions are used to unblock
threads blocked on a condition variable.

The
I<pthread_cond_signal()>
call unblocks at least one of the threads that are blocked on the
specified condition variable
I<cond>
(if any threads are blocked on
I<cond>).

The
I<pthread_cond_broadcast()>
call unblocks all threads currently blocked on the specified condition variable
I<cond>.

If more than one thread is blocked on a condition variable,
the scheduling policy determines the order in which threads are unblocked.
When each thread unblocked as a result of a
I<pthread_cond_signal()>
or
I<pthread_cond_broadcast()>
returns from its call to
I<pthread_cond_wait()>
or
I<pthread_cond_timedwait()>,
the thread owns the mutex with which it called
I<pthread_cond_wait()>
or
I<pthread_cond_timedwait()>.
The thread(s) that are unblocked contend for the mutex
according to the scheduling policy (if applicable),
and as if each had called
I<pthread_mutex_lock()>.

The
I<pthread_cond_signal()>
or
I<pthread_cond_broadcast()>
functions may be called by a thread whether or not it
currently owns the mutex that threads calling
I<pthread_cond_wait()>
or
I<pthread_cond_timedwait()>
have associated with the condition variable during their waits;
however, if predictable scheduling behaviour is required,
then that mutex is locked by the thread calling
I<pthread_cond_signal()>
or
I<pthread_cond_broadcast()>.

The
I<pthread_cond_signal()>
and
I<pthread_cond_broadcast()>
functions have no effect if there are no threads
currently blocked on
I<cond>.

=head1 RETURN VALUE

If successful, the
I<pthread_cond_signal()>
and
I<pthread_cond_broadcast()>
functions return zero.
Otherwise, an error number is returned to indicate the error.

=head1 ERRORS

The
I<pthread_cond_signal()>
and
I<pthread_cond_broadcast()>
function may fail if:

=over 4

=item [EINVAL]

The value
I<cond>
does not refer to an initialised condition variable.

=back

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

=head1 EXAMPLES

None.

=head1 APPLICATION USAGE

None.

=head1 FUTURE DIRECTIONS

None.

=head1 SEE ALSO

I<pthread_cond_init()>,
I<pthread_cond_wait()>,
I<pthread_cond_timedwait()>,
I<<pthread.h>>.


=head1 ______________________________________________________________________

=head1 NAME

B<pthread_cond_init,> B<pthread_cond_destroy> - initialise and destroy
condition variables

=head1 SYNOPSIS

#include <pthread.h>

int pthread_cond_init(pthread_cond_t *I<cond>,
const pthread_condattr_t *I<attr>);
int pthread_cond_destroy(pthread_cond_t *I<cond>);
pthread_cond_t I<cond> = PTHREAD_COND_INITIALIZER;

=head1 DESCRIPTION

The function
I<pthread_cond_init()>
initialises the condition variable referenced by
I<cond>
with attributes referenced by
I<attr>.
If
I<attr>
is NULL,
the default condition variable attributes are used;
the effect is the same as passing the address
of a default condition variable attributes object.
Upon successful initialisation,
the state of the condition variable becomes initialised.

Attempting to initialise an already initialised
condition variable
results in undefined behaviour.

The function
I<pthread_cond_destroy()>
destroys the given condition variable specified by
I<cond>;
the object becomes, in effect, uninitialised.
An implementation may cause
I<pthread_cond_destroy()>
to set the object referenced by
I<cond>
to an invalid value.
A destroyed condition variable object
can be re-initialised using
I<pthread_cond_init()>;
the results of otherwise referencing the object after it has been destroyed
are undefined.

It is safe to destroy an initialised condition variable
upon which no threads are currently blocked.
Attempting to destroy a condition variable
upon which other threads are currently blocked
results in undefined behaviour.

In cases where default condition variable attributes are appropriate,
the macro PTHREAD_COND_INITIALIZER
can be used to initialise condition variables that are statically allocated.
The effect is equivalent to dynamic initialisation by a call to
I<pthread_cond_init()>
with parameter
I<attr>
specified as NULL, except that no error checks are performed.

=head1 RETURN VALUE

If successful, the
I<pthread_cond_init()>
and
I<pthread_cond_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 caused an error return
prior to modifying the state of the condition variable specified by
I<cond>.

=head1 ERRORS

The
I<pthread_cond_init()>
function will fail if:

=over 4

=item [EAGAIN]

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

=item [ENOMEM]

Insufficient memory exists to initialise the condition variable.

=back

The
I<pthread_cond_init()>
function may fail if:

=over 4

=item [EBUSY]

The implementation has detected an attempt
to re-initialise the object referenced by
I<cond>,
a previously initialised, but
not yet destroyed, condition variable.

=item [EINVAL]

The value specified by
I<attr>
is invalid.

=back



The
I<pthread_cond_destroy()>
function may fail if:

=over 4

=item [EBUSY]

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

=item [EINVAL]

The value specified by
I<cond>
is invalid.

=back

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

=head1 EXAMPLES

None.

=head1 APPLICATION USAGE

None.

=head1 FUTURE DIRECTIONS

None.

=head1 SEE ALSO

I<pthread_cond_signal()>,
I<pthread_cond_broadcast()>,
I<pthread_cond_wait()>,
I<pthread_cond_timedwait()>,
I<<pthread.h>>.

=head1 ______________________________________________________________________

=head1 NAME

B<pthread_cond_init,> B<pthread_cond_destroy> - initialise and destroy
condition variables

=head1 SYNOPSIS

#include <pthread.h>

int pthread_cond_init(pthread_cond_t *I<cond>,
const pthread_condattr_t *I<attr>);
int pthread_cond_destroy(pthread_cond_t *I<cond>);
pthread_cond_t I<cond> = PTHREAD_COND_INITIALIZER;

=head1 DESCRIPTION

The function
I<pthread_cond_init()>
initialises the condition variable referenced by
I<cond>
with attributes referenced by
I<attr>.
If
I<attr>
is NULL,
the default condition variable attributes are used;
the effect is the same as passing the address
of a default condition variable attributes object.
Upon successful initialisation,
the state of the condition variable becomes initialised.

Attempting to initialise an already initialised
condition variable
results in undefined behaviour.

The function
I<pthread_cond_destroy()>
destroys the given condition variable specified by
I<cond>;
the object becomes, in effect, uninitialised.
An implementation may cause
I<pthread_cond_destroy()>
to set the object referenced by
I<cond>
to an invalid value.
A destroyed condition variable object
can be re-initialised using
I<pthread_cond_init()>;
the results of otherwise referencing the object after it has been destroyed
are undefined.

It is safe to destroy an initialised condition variable
upon which no threads are currently blocked.
Attempting to destroy a condition variable
upon which other threads are currently blocked
results in undefined behaviour.

In cases where default condition variable attributes are appropriate,
the macro PTHREAD_COND_INITIALIZER
can be used to initialise condition variables that are statically allocated.
The effect is equivalent to dynamic initialisation by a call to
I<pthread_cond_init()>
with parameter
I<attr>
specified as NULL, except that no error checks are performed.

=head1 RETURN VALUE

If successful, the
I<pthread_cond_init()>
and
I<pthread_cond_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 caused an error return
prior to modifying the state of the condition variable specified by
I<cond>.

=head1 ERRORS

The
I<pthread_cond_init()>
function will fail if:

=over 4

=item [EAGAIN]

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

=item [ENOMEM]

Insufficient memory exists to initialise the condition variable.

=back

The
I<pthread_cond_init()>
function may fail if:

=over 4

=item [EBUSY]

The implementation has detected an attempt
to re-initialise the object referenced by
I<cond>,
a previously initialised, but
not yet destroyed, condition variable.

=item [EINVAL]

The value specified by
I<attr>
is invalid.

=back



The
I<pthread_cond_destroy()>
function may fail if:

=over 4

=item [EBUSY]

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

=item [EINVAL]

The value specified by
I<cond>