Guide to DECthreads
pthread_attr_setstackaddr
Changes the stack address attribute of the specified thread attributes
object.
Syntax
pthread_attr_setstackaddr( attr , stackaddr );
Argument |
Data Type |
Access |
attr
|
opaque pthread_attr_t
|
write
|
stackaddr
|
void
|
read
|
C Binding #include <pthread.h> int
pthread_attr_setstackaddr (
pthread_attr_t *attr,
void *stackaddr);
Arguments
attr
Address of the thread attributes object whose stack address attribute
is to be modified.
stackaddr
New value for the stack address attribute of the thread attributes
object specified by attr.
Description
This routine uses the value specified in the stackaddr
argument to set the stack address attribute of the thread attributes
object specified in the attr argument.
When creating a thread, use a thread attributes object to specify
nondefault values for thread attributes. The stack address attribute of
a thread attributes object points to the origin of the stack for a new
thread.
The default value for the stack address attribute of an initialized
thread attributes object is NULL.
Note
Correct use of this routine depends upon details of the target
platform's stack architecture. Thus, this routine cannot be used in a
portable manner.
The size of the stack must be at least PTHREAD_STACK_MIN bytes
(see the pthread.h header file). However, because DECthreads
must use a portion of this stack memory to begin thread execution and
to maintain thread state, your program's "user thread code"
cannot rely on using all of the stack memory allocated.
|
For your program to calculate a value for the stackaddr attribute, note
that:
- Your program must allocate the memory that will be used for the
new thread's stack.
- On DIGITAL UNIX, to create a new thread using a thread attributes
object, the stackaddr attribute must be an address that points to the
high-memory end of the memory region allocated for the stack. This
address must point to the highest even-boundary quadword in the
allocated memory region.
Also note that:
- If you use the pthread_attr_setstackaddr() routine to set
a thread attributes object's stack address attribute and use that
attributes object to create a new thread, DECthreads ignores the
attributes object's guardsize attribute and provides no thread stack
guard area for the new thread.
- If you use the same thread attributes object to create more than
one thread and each created thread uses a nondefault stack address, you
must use the pthread_attr_setstackaddr() routine to set a
unique stack address attribute value for each new thread created using
that attributes object.
Return Values If an error condition occurs, this routine
returns an integer value indicating the type of error. Possible return
values are as follows:
Return |
Description |
0
|
Successful completion.
|
Associated Routines
- pthread_attr_getguardsize()
- pthread_attr_getstackaddr()
- pthread_attr_getstacksize()
- pthread_attr_init()
- pthread_attr_setguardsize()
- pthread_attr_setstacksize()
- pthread_create()
pthread_attr_setstacksize
Changes the stacksize attribute in the specified thread attributes
object.
Syntax
pthread_attr_setstacksize( attr , stacksize );
Argument |
Data Type |
Access |
attr
|
opaque pthread_attr_t
|
write
|
stacksize
|
size_t
|
read
|
C Binding #include <pthread.h> int
pthread_attr_setstacksize (
pthread_attr_t *attr,
size_t stacksize);
Arguments
attr
Threads attributes object to be modified.
stacksize
New value for the stacksize attribute of the thread attributes object
specified by the attr argument. The stacksize
argument must be greater than or equal to PTHREAD_STACK_MIN.
PTHREAD_STACK_MIN specifies the minimum size (in bytes) of
stack needed for a thread.
Description
This routine sets the stacksize attribute in the thread attributes
object specified by the attr argument. Use this routine to
adjust the size of the writable area of the stack for a new thread.
The size of a thread's stack is fixed at the time of thread creation.
Only the initial thread can dynamically extend its stack.
Many compilers do not check for stack overflow. Ensure that the new
thread's stack is sufficient for the resources required by routines
that are called from the thread.
Return Values If an error condition occurs, this routine
returns an integer value indicating the type of error. Possible return
values are as follows:
Return |
Description |
0
|
Successful completion.
|
[EINVAL]
|
The value specified by
attr is invalid, or the value specified by
stacksize is less than
PTHREAD_STACK_MIN or exceeds a DECthreads-imposed limit.
|
Associated Routines
- pthread_attr_init()
- pthread_attr_getstacksize()
- pthread_create()
pthread_cancel
Allows a thread to request a thread to terminate execution.
Syntax
pthread_cancel( thread );
Argument |
Data Type |
Access |
thread
|
opaque pthread_t
|
read
|
C Binding #include <pthread.h> int
pthread_cancel (
pthread_t thread);
Arguments
thread
Thread that receives a cancelation request.
Description
This routine sends a cancelation request to the specified target
thread. A cancelation request is a mechanism by which a
calling thread requests the target thread to terminate as quickly as
possible. Issuing a cancelation request does not guarantee that the
target thread will receive or handle the request.
When the cancelation request is acted on, all active cleanup handler
routines for the target thread are called. When the last cleanup
handler returns, the thread-specific data destructor routines are
called for each thread-specific data key with a destructor and for
which the target thread has a non-NULL value. Finally, the target
thread is terminated.
Note that cancelation of the target thread runs asynchronously with
respect to the calling thread's returning from
pthread_cancel(). The target thread's cancelability state and
type determine when or if the cancelation takes place, as follows:
- The target thread can delay cancelation during critical operations
by setting its cancelability state to PTHREAD_CANCEL_DISABLE.
- Because of communication delays, the calling thread can only rely
on the fact that a cancelation request will eventually become pending
in the target thread (provided that the target thread does not
terminate beforehand).
- The calling thread has no guarantee that a pending cancelation
request will be delivered because delivery is controlled by the target
thread.
When a cancelation request is delivered to a thread, termination
processing is similar to that for pthread_exit(). For more
information about thread termination, see the Thread Termination
section of pthread_create().
This routine is preferred in implementing an Ada abort
statement and any other language- or software-defined construct for
requesting thread cancelation.
The results of this routine are unpredictable, if the value specified
in thread refers to a thread that does not currently exist.
Return Values If an error condition occurs, this routine
returns an integer indicating the type of error. Possible return values
are as follows:
Return |
Description |
0
|
Successful completion.
|
[EINVAL]
|
The specified
thread is invalid.
|
[ESRCH]
|
The
thread argument does not specify an existing thread.
|
Associated Routines
- pthread_cleanup_pop()
- pthread_cleanup_push()
- pthread_create()
- pthread_exit()
- pthread_join()
- pthread_setcancelstate()
- pthread_setcanceltype()
- pthread_testcancel()
pthread_cleanup_pop
(Macro) Removes the cleanup handler routine from the calling thread's
cleanup handler stack and optionally executes it.
Syntax
pthread_cleanup_pop( execute );
Argument |
Data Type |
Access |
execute
|
integer
|
read
|
C Binding #include <pthread.h> void
pthread_cleanup_pop(
int execute);
Arguments
execute
Integer that specifies whether the cleanup handler routine specified in
the matching call to pthread_cleanup_push() is executed. A
nonzero value causes the cleanup handler routine to be executed.
Description
This routine removes the cleanup handler routine established by the
matching call to pthread_cleanup_push() from the calling
thread's cleanup handler stack, then executes it if the value specified
in this routine's execute argument is nonzero.
A cleanup handler routine can be used to clean up from a block of code
whether exited by normal completion, cancelation, or the raising (or
reraising) of an exception. The routine is popped from the calling
thread's cleanup handler stack and is executed with the arg
argument when any of the following actions occur:
- The thread calls pthread_cleanup_pop() and specifies a
nonzero value for the execute argument.
- The thread calls pthread_exit().
- The thread is canceled.
- An exception is raised and is caught when DECthreads unwinds the
calling thread's stack to the lexical scope of the
pthread_cleanup_push() and pthread_cleanup_pop() pair.
This routine and pthread_cleanup_push() are implemented as
macros and must appear as statements and in pairs within the same
lexical scope. You can think of the pthread_cleanup_push()
macro as expanding to a string whose first character is a left brace
({) and pthread_cleanup_pop() as expanding to a string
containing the corresponding right brace (}).
Return Values None
Associated Routines
- pthread_cancel()
- pthread_cleanup_push()
- pthread_create()
- pthread_exit()
pthread_cleanup_push
(Macro) Establishes a cleanup handler routine to be executed when the
thread exits or is canceled.
Syntax
pthread_cleanup_push( routine, arg );
Argument |
Data Type |
Access |
routine
|
procedure
|
read
|
arg
|
user_arg
|
read
|
C Binding #include <phtread.h> void
pthread_cleanup_push(
void (*routine)(void *),
void *arg);
Arguments
routine
Routine executed as the cleanup handler.
arg
Argument passed to the cleanup handler routine.
Description
This routine pushes the specified routine onto the calling thread's
cleanup handler stack. The cleanup handler routine is popped from the
stack and executed with the arg argument when any of the
following actions occur:
- The thread calls pthread_cleanup_pop() and specifies a
nonzero value for the execute argument.
- The thread calls pthread_exit().
- The thread is canceled.
- An exception is raised and is caught when DECthreads unwinds the
calling thread's stack to the lexical scope of the
pthread_cleanup_push() and pthread_cleanup_pop() pair.
This routine and pthread_cleanup_pop() are implemented as
macros and must appear as statements and in pairs within the same
lexical scope. You can think of the pthread_cleanup_push()
macro as expanding to a string whose first character is a left brace
({) and pthread_cleanup_pop() as expanding to a string
containing the corresponding right brace (}).
Return Values None
Associated Routines
- pthread_cancel()
- pthread_cleanup_pop()
- pthread_create()
- pthread_exit()
- pthread_testcancel()
pthread_condattr_destroy
Destroys a condition variable attributes object.
Syntax
pthread_condattr_destroy( attr );
Argument |
Data Type |
Access |
attr
|
opaque pthread_condattr_t
|
write
|
C Binding #include <pthread.h> int
pthread_condattr_destroy (
pthread_condattr_t *attr);
Arguments
attr
Condition variable attributes object to be destroyed.
Description
This routine destroys the specified condition variable attributes
object---that is, the object becomes uninitialized.
Condition variables that were created using this attributes object are
not affected by the deletion of the condition variable attributes
object.
After calling this routine, the results of using attr in a
call to any routine (other than pthread_condattr_init()) are
unpredictable.
Return Values If an error condition occurs, this routine
returns an integer value indicating the type of error. Possible return
values are as follows:
Return |
Description |
0
|
Successful completion.
|
[EINVAL]
|
The attributes object specified by
attr is invalid.
|
Associated Routines
pthread_condattr_getpshared
Obtains the process-shared attribute of the specified condition
variable attributes object.
This routine is for DIGITAL UNIX systems only.
Syntax
pthread_condattr_getpshared( attr , pshared );
Argument |
Data Type |
Access |
attr
|
opaque pthread_condattr_t
|
read
|
pshared
|
int
|
write
|
C Binding #include <pthread.h> int
pthread_condattr_getpshared (
const pthread_condattr_t *attr,
int *pshared);
Arguments
attr
Address of the condition variable attributes object whose
process-shared attribute is obtained.
pshared
Receives the value of the process-shared attribute of the condition
variable attributes object specified by attr.
Description
This routine obtains the value of the process-shared attribute of the
condition variable attributes object specified by the attr
argument and stores it in the location specified by the
pshared argument. The specified attributes object must already
be initialized at the time this routine is called.
Creating a condition variable whose process-shared attribute is set to
PTHREAD_PROCESS_PRIVATE permits it to be operated upon by
threads created within the same process as the thread that initialized
that condition variable. If threads in other processes attempt to
operate on such a condition variable, the behavior is undefined.
The default value of the process-shared attribute of an initialized
condition variable attributes object is
PTHREAD_PROCESS_PRIVATE.
Creating a condition variable whose process-shared attribute is set to
PTHREAD_PROCESS_SHARED permits it to be operated upon by any
thread that has access to the memory where that condition variable is
allocated, even if it is allocated in memory that is shared by multiple
processes.
Return Values If an error condition occurs, this routine
returns an integer value indicating the type of error. Possible return
values are as follows:
Return |
Description |
0
|
Successful completion.
|
[EINVAL]
|
The value specified by
attr is invalid.
|
Associated Routines
- pthread_condattr_destroy()
- pthread_condattr_init()
- pthread_condattr_setpshared()
- pthread_cond_init()
pthread_condattr_init
Initializes a condition variable attributes object.
Syntax
pthread_condattr_init( attr );
Argument |
Data Type |
Access |
attr
|
opaque pthread_condattr_t
|
write
|
C Binding #include <pthread.h> int
pthread_condattr_init (
pthread_condattr_t *attr);
Arguments
attr
Address of the condition variable attributes object to be initialized.
Description
This routine initializes the condition variable attributes object
specified by the attr argument with a set of default attribute
values.
When an attributes object is used to create a condition variable, the
values of the individual attributes determine the characteristics of
the new condition variable. Attributes objects act as additional
arguments to condition variable creation. Changing individual
attributes in an attributes object does not affect any condition
variables that were previously created using that attributes object.
You can use the same condition variable attributes object in successive
calls to pthread_condattr_init(), from any thread. If multiple
threads can change attributes in a shared attributes object, your
program must use a mutex to protect the integrity of that attributes
object.
Results are undefined if this routine is called and the attr
argument specifies a condition variable attributes object that is
already initialized.
Currently, no attributes affecting condition variables are defined. You
cannot change any attributes in the condition variable attributes
object.
The pthread_condattr_init() and
pthread_condattr_destroy() routines are provided for future
expandability of the DECthreads pthread interface and
to conform with the POSIX.1c standard. These routines serve no useful
function, because there are no pthread_condattr_set*() type
routines available at this time.
Return Values If an error condition occurs, this routine
returns an integer value indicating the type of error. Possible return
values are as follows:
Return |
Description |
0
|
Successful completion.
|
[ENOMEM]
|
Insufficient memory exists to initialize the condition variable
attributes object.
|
Associated Routines
- pthread_condattr_destroy()
- pthread_cond_init()
|