IBM Extension

Pthreads library module

The Pthreads Library Module (f_pthread) is a Fortran 90 module that defines data types and routines to make it easier to interface with the Linux pthreads library. The Linux pthreads library is used to parallelize and thread-safe your code. The f_pthread library module naming convention is the use of the prefix f_ before the corresponding Linux pthreads library routine name or type definition name.

In general, there is a one-to-one corresponding relationship between the procedures in the Fortran 90 module f_pthread and the library routines contained in the Linux pthreads library. However, some of the pthread routines have no corresponding procedures in this module because they are not supported on Linux. One example of these routines is the thread stack address option. There are also some non-pthread interfacing routines contained in the f_pthread library module. The f_maketime routine is one example and is included to return an absolute time in a f_timespec derived type variable.

Most of the routines return an integer value. A return value of 0 will always indicate that the routine call did not result in any error. Any non-zero return value indicates an error. Each error code has a corresponding definition of a system error code in Fortran. These error codes are available as Fortran integer constants. The naming of these error codes in Fortran is consistent with the corresponding Linux error code names. For example, EINVAL is the Fortran constant name of the error code EINVAL on Linux. For a complete list of these error codes, refer to the file /usr/include/errno.h on Linux.

Pthreads data structures, functions, and subroutines

Pthreads Data Types

Functions that perform operations on thread attribute objects

Functions and Subroutines That Perform Operations on Threads

Functions that perform operations on mutex attribute objects

Functions that perform operations on mutex objects

Functions that perform operations on attribute objects of condition variables

Functions that perform operations on condition variable objects

Functions that perform operations on thread-specific data

Functions and subroutines that perform operations to control thread cancelability

Functions that perform operations on read-write lock attribute objects

Functions that perform operations on read-write lock objects

Functions that perform operations for one-time initialization

f_maketime(delay)

Purpose

This function accepts an integer value specifying a delay in seconds and returns an f_timespec type object containing the absolute time, which is delay seconds from the calling moment.

Class

Function

Argument Type and Attributes

delay
INTEGER(4), INTENT(IN)

Result Type and Attributes

TYPE (f_timespec)

Result Value

The absolute time, which is delay seconds from the calling moment, is returned.

f_pthread_attr_destroy(attr)

Purpose

This function must be called to destroy any previously initialized thread attribute objects when they will no longer be used. Threads that were created with this attribute object will not be affected in any way by this action. Memory that was allocated when it was initialized will be recollected by the system.

Class

Function

Argument Type and Attributes

attr
TYPE(f_pthread_attr_t), INTENT(IN)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The argument attr is invalid.

f_pthread_attr_getdetachstate(attr, detach)

Purpose

This function can be used to query the setting of the detach state attribute in the thread attribute object attr. The current setting will be returned through argument detach.

Class

Function

Argument Type and Attributes

attr
TYPE(f_pthread_attr_t), INTENT(IN)
detach
INTEGER(4), INTENT(OUT)

Contains one of the following values:

PTHREAD_CREATE_DETACHED:
when a thread attribute object of this attribute setting is used to create a new thread, the newly created thread will be in detached state. This is the system default.
PTHREAD_CREATE_JOINABLE:
when a thread attribute object of this attribute setting is used to create a new thread, the newly created thread will be in undetached state.

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error:

EINVAL
The argument attr is invalid.

f_pthread_attr_getguardsize(attr, guardsize)

Purpose

This function is used to get the guardsize attribute in the thread attribute object attr. The current setting of the attribute will be returned through the argument guardsize.

Class

Function

Argument Type and Attributes

attr
TYPE(f_pthread_attr_t), INTENT(IN)
guardsize
INTEGER(KIND=register_size), INTENT(IN)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error:

EINVAL
The argument attr is invalid.

f_pthread_attr_getinheritsched(attr, inherit)

Purpose

This function can be used to query the inheritance scheduling attribute in the thread attribute object attr. The current setting will be returned through the argument inherit.

Class

Function

Argument Type and Attributes

attr
TYPE(f_pthread_attr_t), INTENT(OUT)
inherit
INTEGER(4)

On return from the function, inherit contains one of the following values:

PTHREAD_INHERIT_SCHED:
indicating that newly created threads will inherit the scheduling property of the parent thread and ignore the scheduling property of the thread attribute object used to create them.
PTHREAD_EXPLICIT_SCHED:
the scheduling property in the thread attribute object will be assigned to the newly created threads when it is used to create them.

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise this function returns the following error.

EINVAL
The argument attr is invalid.

f_pthread_attr_getschedparam(attr, param)

Purpose

This function can be used to query the scheduling property setting in the thread attribute object attr. The current setting will be returned in the argument param.

Class

Function

Argument Type and Attributes

attr
TYPE(f_pthread_attr_t), INTENT(IN)
param
TYPE(f_sched_param), INTENT(OUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The argument attr is invalid.

f_pthread_attr_getschedpolicy(attr, policy)

Purpose

This function can be used to query the scheduling policy attribute setting in the attribute object attr. The current setting of the scheduling policy will be returned in the argument policy.

Class

Function

Argument Type and Attributes

attr
TYPE(f_pthread_attr_t), INTENT(IN)
policy
INTEGER(4), INTENT(OUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The argument attr is invalid.

f_pthread_attr_getscope(attr, scope)

Purpose

This function can be used to query the current setting of the scheduling scope attribute in the thread attribute object attr. The current setting will be returned through the argument scope.

Class

Function

Argument Type and Attributes

attr
TYPE(f_pthread_attr_t), INTENT(IN)
scope
INTEGER(4), INTENT(OUT)

On return from the function, scope will contain one of the following values:

PTHREAD_SCOPE_SYSTEM:
the thread will compete for system resources on a system wide scope.
PTHREAD_SCOPE_PROCESS:
the thread will compete for system resources locally within the owning process.
scope
Contains the following value:
PTHREAD_SCOPE_SYSTEM:
the thread will compete for system resources on a system wide scope.

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The argument attr is invalid.

f_pthread_attr_getstack(attr, stackaddr, ssize)

Purpose

Retrieves the values of the stackaddr and stacksize arguments from the thread attribute object attr.

Class

Function

Argument Type and Attributes

attr
TYPE(f_pthread_attr_t), INTENT(IN)
stackaddr
Integer pointer, INTENT(OUT)
ssize
INTEGER(KIND=register_size), INTENT(OUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
One or more of the supplied arguments is invalid.

f_pthread_attr_init(attr)

Purpose

This function must be called to create and initialize the pthread attribute object attr before it can be used in any way. It will be filled with system default thread attribute values. After it is initialized, certain pthread attributes can be changed and/or set through attribute access procedures. Once initialized, this attribute object can be used to create a thread with the intended attributes.

Class

Function

Argument Type and Attributes

attr
TYPE(f_pthread_attr_t), INTENT(OUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The argument attr is invalid.

f_pthread_attr_setdetachstate(attr, detach)

Purpose

This function can be used to set the detach state attribute in the thread attribute object attr.

Class

Function

Argument Type and Attributes

attr
TYPE(f_pthread_attr_t), INTENT(OUT)
detach
INTEGER(4), INTENT(IN)

Must contain one of the following values:

PTHREAD_CREATE_DETACHED:
when a thread attribute object of this attribute setting is used to create a new thread, the newly created thread will be in detached state. This is the system default setting.
PTHREAD_CREATE_JOINABLE:
when a thread attribute object of this attribute setting is used to create a new thread, the newly created thread will be in undetached state.

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The argument detach is invalid.

f_pthread_attr_setguardsize(attr, guardsize)

Purpose

This function is used to set the guardsizeattribute in the thread attributes object attr. The new value of this attribute is obtained from the argument guardsize. If guardsize is zero, a guard area will not be provided for threads created with attr. If guardsize is greater than zero, a guard area of at least sizeguardsize bytes is provided for each thread created with attr.

Class

Function

Argument Type and Attributes

attr
TYPE(f_pthread_attr_t), INTENT(INOUT)
guardsize
INTEGER(KIND=register_size), INTENT(IN)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The argument attr or the argument guardsize is invalid.

f_pthread_attr_setinheritsched(attr, inherit)

Purpose

This function can be used to set the inheritance attribute of the thread scheduling property in the thread attribute object attr.

Class

Function

Argument Type and Attributes

attr
TYPE(f_pthread_attr_t), INTENT(OUT)
inherit
INTEGER(4), INTENT(IN)

Must contain one of the following values:

PTHREAD_INHERIT_SCHED:
indicating that newly created threads will inherit the scheduling property of the parent thread and ignore the scheduling property of the thread attribute object used to create them.
PTHREAD_EXPLICIT_SCHED:
the scheduling property in the thread attribute object will be assigned to the newly created threads when it is used to create them.

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The argument inherit is invalid.

f_pthread_attr_setschedparam(attr, param)

Purpose

This function can be used to set the scheduling property attribute in the thread attribute object attr. Threads created with this new attribute object will assume the scheduling property of argument param if they are not inherited from the creating thread. The sched_priority field in argument param indicates the thread's scheduling priority. The priority field must assume a value in the range of 1-127, where 127 is the most favored scheduling priority while 1 is the least.

Class

Function

Argument Type and Attributes

attr
TYPE(f_pthread_attr_t), INTENT(INOUT)
param
TYPE(f_sched_param), INTENT(IN)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The argument param is invalid.

f_pthread_attr_setschedpolicy(attr, policy)

Purpose

After the attribute object is set by this function, threads created with this attribute object will assume the set scheduling policy if the scheduling property is not inherited from the creating thread.

Class

Function

Argument Type and Attributes

attr
TYPE(f_pthread_attr_t), INTENT(INOUT)
policy
INTEGER(4), INTENT(IN)

Must contain one of the following values:

SCHED_FIFO:
indicating a first-in first-out thread scheduling policy.
SCHED_RR:
indicating a round-robin scheduling policy.
SCHED_OTHER:
the default scheduling policy.

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following error.

EINVAL
The argument policy is invalid.

f_pthread_attr_setscope(attr, scope)

Purpose

This function can be used to set the contention scope attribute in the thread attribute object attr.

Argument scope must contain one of the following values:

Class

Function

Argument Type and Attributes

attr
TYPE(f_pthread_attr_t), INTENT(INOUT)
scope
INTEGER(4), INTENT(IN)

Must contain one of the following values:

PTHREAD_SCOPE_SYSTEM:
the thread will compete for system resources on a system wide scope.
PTHREAD_SCOPE_PROCESS:
the thread will compete for system resources locally within the owning process.

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The argument scope is invalid.

f_pthread_attr_setstack(attr, stackaddr, ssize)

Purpose

Use this function to set the stack address and stack size attributes in the pthread attribute object attr. The stackaddr argument represents the stack address as an Integer pointer. The stacksize argument is an integer that represents the size of the stack in bytes. When creating a thread using the attribute object attr, the system allocates a minimum stack size of stacksize bytes.

Class

Function

Argument Type and Attributes

attr
TYPE(f_pthread_attr_t), INTENT(INOUT)
stackaddr
Integer pointer, INTENT(IN)
ssize
INTEGER(KIND=register_size)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following errors.

EINVAL
The value of one or both of the supplied arguments is invalid.
EACCES
The stack pages specified are not readable by the thread.

f_pthread_attr_t

Purpose

A derived data type whose components are all private. Any object of this type should be manipulated only through the appropriate interfaces provided in this module.

This data type corresponds to the POSIX pthread_attr_t, which is the type of thread attribute object.

Class

Data Type.

f_pthread_cancel(thread)

Purpose

This function can be used to cancel a target thread. How this cancelation request will be processed depends on the state of the cancelability of the target thread. The target thread is identified by argument thread. If the target thread is in deferred-cancel state, this cancelation request will be put on hold until the target thread reaches its next cancelation point. If the target thread disables its cancelability, this request will be put on hold until it is enabled again. If the target thread is in async-cancel state, this request will be acted upon immediately.

Class

Function

Argument Type and Attributes

thread
TYPE(f_pthread_t), INTENT(INOUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

ESRCH
The argument thread is invalid.

f_pthread_cleanup_pop(exec)

Purpose

This subroutine should be paired with f_pthread_cleanup_push in using the cleanup stack for thread safety. If the supplied argument exec contains a non-zero value, the last pushed cleanup function will be popped from the cleanup stack and executed, with the argument arg (from the last f_pthread_cleanup_push) passed to the cleanup function.

If exec contains a zero value, the last pushed cleanup function will be popped from the cleanup stack, but will not be executed.

Class

Subroutine

Argument Type and Attributes

exec
INTEGER(4), INTENT(IN)

Result Type and Attributes

None.

Result Value

None.

f_pthread_cleanup_push(cleanup, flag, arg)

Purpose

This function can be used to register a cleanup subroutine for the calling thread. In case of an unexpected termination of the calling thread, the system will automatically execute the cleanup subroutine in order for the calling thread to terminate safely. The argument cleanup must be a subroutine expecting exactly one argument. If it is executed, the argument arg will be passed to it as the actual argument.

The argument arg is a generic argument that can be of any type and any rank. The actual argument arg must be a variable, and consequently eligible as a left-value in an assignment statement. If you pass an array section with vector subscripts to the argument arg, the result is unpredictable.

If the actual argument arg is an array section, the corresponding dummy argument in subroutine cleanup must be an assumed-shape array. Otherwise, the result is unpredictable.

If the actual argument arg has the pointer attribute that points to an array or array section, the corresponding dummy argument in subroutine cleanup must have a pointer attribute or be an assumed-shape array. Otherwise, the result is unpredictable.

For a normal execution path, this function must be paired with a call to f_pthread_cleanup_pop.

The argument flag must be used to convey the property of argument arg exactly to the system.

Class

Function

Argument Type and Attributes

cleanup
A subroutine that has one dummy argument.
flag
Flag is an INTEGER(4), INTENT(IN) argument that can contain one of, or a combination of, the following constants:
FLAG_CHARACTER:
if the entry subroutine cleanup expects an argument of type CHARACTER in any way or any form, this flag value must be included to indicate this fact. However, if the subroutine expects a Fortran 90 pointer pointing to an argument of type CHARACTER, the FLAG_DEFAULT value should be included instead.
FLAG_ASSUMED_SHAPE:
if the entry subroutine cleanup has a dummy argument that is an assumed-shape array of any rank, this flag value must be included to indicate this fact.
FLAG_DEFAULT:
otherwise, this flag value is needed.
arg
A generic argument that can be of any type, kind, and rank.

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following errors.

ENOMEM
The system cannot allocate memory to push this routine.
EAGAIN
The system cannot allocate resources to push this routine.
EINVAL
The argument flag is invalid.

f_pthread_cond_broadcast(cond)

Purpose

This function will unblock all threads waiting on the condition variable cond. If there is no thread waiting on this condition variable, the function will still succeed, but the next caller to f_pthread_cond_wait will be blocked, and will wait on the condition variable cond.

Class

Function

Argument Type and Attributes

cond
TYPE(f_pthread_cond_t), INTENT(INOUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns following error.

EINVAL
The argument cond is invalid.

f_pthread_cond_destroy(cond)

Purpose

This function can be used to destroy those condition variables that are no longer required. The target condition variable is identified by the argument cond. System resources allocated during initialization will be recollected by the system.

Class

Function

Argument Type and Attributes

cond
TYPE(f_pthread_cond_t), INTENT(INOUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EBUSY
The condition variable cond is being used by another thread.

f_pthread_cond_init(cond, cattr)

Purpose

This function can be used to dynamically initialize a condition variable cond. Its attributes will be set according to the attribute object cattr, if it is provided; otherwise, its attributes will be set to the system default. After the condition variable is initialized successfully, it can be used to synchronize threads.

Another method of initializing a condition variable is to initialize it statically using the Fortran constant PTHREAD_COND_INITIALIZER.

Class

Function

Argument Type and Attributes

cond
TYPE(f_pthread_cond_t), INTENT(INOUT)
cattr
TYPE(f_pthread_condattr_t), INTENT(IN), OPTIONAL

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following errors.

EBUSY
The condition variable is already in use. It is initialized and not destroyed.
EINVAL
The argument cond or cattr is invalid.

f_pthread_cond_signal(cond)

Purpose

This function will unblock at least one thread waiting on the condition variable cond. If there is no thread waiting on this condition variable, the function will still succeed, but the next caller to f_pthread_cond_wait will be blocked, and will wait on the condition variable cond.

Class

Function

Argument Type and Attributes

cond
TYPE(f_pthread_cond_t), INTENT(INOUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The argument cond is invalid.

f_pthread_cond_t

Purpose

A derived data type whose components are all private. Any object of this type should be manipulated through the appropriate interfaces provided in this module. In addition, objects of this type can be initialized at compile time using the Fortran constant PTHREAD_COND_INITIALIZER.

This data type corresponds to the POSIX pthread_cond_t, which is the type of condition variable object.

Class

Data Type.

f_pthread_cond_timedwait(cond, mutex, timeout)

Purpose

This function can be used to wait for a certain condition to occur. The argument mutex must be locked before calling this function. The mutex is unlocked atomically and the calling thread waits for the condition to occur. The argument timeout specifies a deadline before which the condition must occur. If the deadline is reached before the condition occurs, the function will return an error code. This function provides a cancelation point in that the calling thread can be canceled if it is in the enabled state.

The argument timeout will specify an absolute date of the form: Oct. 31 10:00:53, 1998. For related information, see f_maketime and f_timespec.

Class

Function

Argument Type and Attributes

cond
TYPE(f_pthread_cond_t), INTENT(INOUT)
mutex
TYPE(f_pthread_mutex_t), INTENT(INOUT)
timeout
TYPE(f_timespec), INTENT(IN)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise this function returns one of the following errors:

EINVAL
The argument cond, mutex, or timeout is invalid.
ETIMEDOUT
The waiting deadline was reached before the condition occurred.

f_pthread_cond_wait(cond, mutex)

Purpose

This function can be used to wait for a certain condition to occur. The argument mutex must be locked before calling this function. The mutex is unlocked atomically, and the calling thread waits for the condition to occur. If the condition does not occur, the function will wait until the calling thread is terminated in another way. This function provides a cancelation point in that the calling thread can be canceled if it is in the enabled state.

Class

Function

Argument Type and Attributes

cond
TYPE(f_pthread_cond_t), INTENT(INOUT)
mutex
TYPE(f_pthread_mutex_t), INTENT(INOUT)

Result Type and Attributes

INTEGER(4)

Result Value

This function returns 0.

f_pthread_condattr_destroy(cattr)

Purpose

This function can be called to destroy the condition variable attribute objects that are no longer required. The target object is identified by the argument cattr. The system resources allocated when it is initialized will be recollected.

Class

Function

Argument Type and Attributes

cattr
TYPE(f_pthread_condattr_t), INTENT(INOUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns on of the following errors.

EINVAL
The argument cattr is invalid.
EBUSY
Returns EBUSY if threads are waiting on the for the condition to occur.

f_pthread_condattr_getpshared(cattr, pshared)

Purpose

This function can be used to query the process-shared attribute of the condition variable attributes object identified by the argument cattr. The current setting of this attribute will be returned in the argument pshared.

Class

Function

Argument Type and Attributes

cattr
TYPE(f_pthread_condattr_t), INTENT(IN)
pshared
INTEGER(4), INTENT(OUT)

On successful completion, pshared contains one of the following values:

PTHREAD_PROCESS_SHARED
The condition variable can be used by any thread that has access to the memory where it is allocated, even if these threads belong to different processes.
PTHREAD_PROCESS_PRIVATE
The condition variable shall only be used by threads within the same process as the thread that created it.

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The argument cattr is invalid.

f_pthread_condattr_init(cattr)

Purpose

Use this function to initialize a condition variable attributes object cattr with the default value for all of the attributes defined by the implementation. Attempting to initialize an already initialized condition variable attributes object results in undefined behavior. After a condition variable attributes object has been used to initialize one or more condition variables, any function affecting the attributes object (including destruction) does not affect any previously initialized condition variables.

Class

Function

Argument Type and Attributes

cattr
TYPE(f_pthread_condattr_t), INTENT(OUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

ENOMEM
There is insufficient memory to initialize the condition variable attributes object.

f_pthread_condattr_setpshared(cattr, pshared)

Purpose

This function is used to set the process-shared attribute of the condition variable attributes object identified by the argument cattr. Its process-shared attribute will be set according to the argument pshared.

Class

Function

Argument Type and Attributes

cattr
TYPE(f_pthread_condattr_t), INTENT(INOUT)
pshared
is an INTEGER(4), INTENT(IN) argument that must contain one of the following values:
PTHREAD_PROCESS_SHARED
Specifies that the condition variable can be used by any thread that has access to the memory where it is allocated, even if these threads belong to different processes.
PTHREAD_PROCESS_PRIVATE
Specifies that the condition variable shall only be used by threads within the same process as the thread that created it. This is the default setting of the attribute.

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The value specified by the argument cattr or pshared is invalid.

f_pthread_condattr_t

Purpose

A derived data type whose components are all private. Any object of this type should be manipulated only through the appropriate interfaces provided in this module.

This data type corresponds to the POSIX pthread_condattr_t, which is the type of condition variable attribute object.

Class

Data Type

f_pthread_create(thread, attr, flag, ent, arg)

Purpose

This function is used to create a new thread in the current process. The newly created thread will assume the attributes defined in the thread attribute object attr, if it is provided. Otherwise, the new thread will have system default attributes. The new thread will begin execution at the subroutine ent, which is required to have one dummy argument. The system will pass the argument arg to the thread entry subroutine ent as its actual argument. The argument flag is used to inform the system of the property of the argument arg. When the execution returns from the entry subroutine ent, the new thread will terminate automatically.

If subroutine ent was declared such that an explicit interface would be required if it was called directly, then an explicit interface is also required when it is passed as an argument to this function.

The argument arg is a generic argument that can be of any type and any rank. The actual argument arg must be a variable, and consequently eligible as a left- value in an assignment statement. If you pass an array section with vector subscripts to the argument arg, the result is unpredictable.

If the actual argument arg is an array section, the corresponding dummy argument in subroutine ent must be an assumed-shape array. Otherwise, the result is unpredictable.

If the actual argument arg has the pointer attribute that points to an array or array section, the corresponding dummy argument in subroutine ent must have a pointer attribute or be an assumed-shape array. Otherwise, the result is unpredictable.

Class

Function

Argument Type and Attributes

thread
TYPE(f_pthread_t), INTENT(OUT)

On successful completion of the function, f_pthread_create stores the ID of the created thread in the thread.

attr
TYPE(f_pthread_attr_t), INTENT(IN)
flag
INTEGER(4), INTENT(IN)

The argument flag must convey the property of the argument arg exactly to the system. The argument flag can be one of, or a combination of, the following constants:

FLAG_CHARACTER:
if the entry subroutine ent expects an argument of type CHARACTER in any way or any form, this flag value must be included to indicate this fact. However, if the subroutine expects a Fortran 90 pointer pointing to an argument of type CHARACTER, the FLAG_DEFAULT value should be included instead.
FLAG_ASSUMED_SHAPE:
if the entry subroutine ent has a dummy argument which is an assumed-shape array of any rank, this flag value must be included to indicate this fact.
FLAG_DEFAULT:
otherwise, this flag value is needed.
ent
A subroutine that has one dummy argument.
arg
A generic argument that can be of any type, kind, and rank.

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following errors.

EAGAIN
The system does not have enough resources to create a new thread.
EINVAL
The argument thread, attr, or flag is invalid.
ENOMEM
The system does not have sufficient memory to create a new thread.

f_pthread_detach(thread)

Purpose

This function is used to indicate to the pthreads library implementation that storage for the thread whose thread ID is specified by the argument thread can be claimed when this thread terminates. If the thread has not yet terminated, f_pthread_detach shall not cause it to terminate. Multiple f_pthread_detach calls on the same target thread cause an error.

Class

Function

Argument Type and Attributes

thread
TYPE(f_pthread_t), INTENT(IN)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

ESRCH
The argument thread is invalid.

f_pthread_equal(thread1, thread2)

Purpose

This function can be used to compare whether two thread ID's identify the same thread or not.

Class

Function

Argument Type and Attributes

thread1
TYPE(f_pthread_t), INTENT(IN)
thread2
TYPE(f_pthread_t), INTENT(IN)

Result Type and Attributes

LOGICAL(4)

Result Value

TRUE
The two thread ID's identify the same thread.
FALSE
The two thread ID's do not identify the same thread.

f_pthread_exit(ret)

Purpose

This subroutine can be called explicitly to terminate the calling thread before it returns from the entry subroutine. The actions taken depend on the state of the calling thread. If it is in non-detached state, the calling thread will wait to be joined. If the thread is in detached state, or when it is joined by another thread, the calling thread will terminate safely. First, the cleanup stack will be popped and executed, and then any thread-specific data will be destructed by the destructors. Finally, the thread resources are freed and the argument ret will be returned to the joining threads. The argument ret of this subroutine is optional. Currently, argument ret is limited to be an Integer pointer. If it is not an Integer pointer, the behavior is undefined.

This subroutine never returns. If argument ret is not provided, NULL will be provided as this thread's exit status.

Class

Subroutine

Argument Type and Attributes

ret
Integer pointer, OPTIONAL, INTENT(IN)

Result Type and Attributes

None

Result Value

None

f_pthread_getconcurrency()

Purpose

This function returns the value of the concurrency level set by a previous call to the f_pthread_setconcurrency function. If the f_pthread_setconcurrency function was not previously called, this function returns zero to indicate that the system is maintaining the concurrency level.

Class

Function

Argument Type and Attributes

None

Result Type and Attributes

INTEGER(4)

Result Value

This function returns the value of the concurrency level set by a previous call to the f_pthread_setconcurrency function. If the f_pthread_setconcurrency function was not previously called, this function returns 0.

f_pthread_getschedparam(thread, policy, param)

Purpose

This function can be used to query the current setting of the scheduling property of the target thread. The target thread is identified by argument thread. Its scheduling policy will be returned through argument policy and its scheduling property through argument param. The sched_priority field in param defines the scheduling priority. The priority field will assume a value in the range of 1-127, where 127 is the most favored scheduling priority while 1 is the least.

Class

Function

Argument Type and Attributes

thread
TYPE(f_pthread_t), INTENT(IN)
policy
INTEGER(4), INTENT(OUT)
param
TYPE(f_sched_param), INTENT(OUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following errors.

ESRCH
The target thread is invalid or has already terminated.
EFAULT
The policy or param points are outside the process memory space

f_pthread_getspecific(key, arg)

Purpose

This function can be used to retrieve the thread-specific data associated with key. Note that the argument arg is not optional in this function as it will return the thread-specific data. After execution of the procedure, the argument arg holds a pointer to the data, or NULL if there is no data to retrieve. The argument arg must be an Integer pointer, or the result is undefined.

The actual argument arg must be a variable, and consequently eligible as a left-value in an assignment statement. If you pass an array section with vector subscripts to the argument arg, the result is unpredictable.

Class

Function

Argument Type and Attributes

key
TYPE(f_pthread_key_t), INTENT(IN)
arg
Integer pointer, INTENT(OUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The argument key is invalid.

f_pthread_join(thread, ret)

Purpose

This function can be called to join a particular thread designated by the argument thread. If the target thread is in non-detached state and is already terminated, this call will return immediately with the target thread's status returned in argument ret if it is provided. The argument ret is optional. Currently, ret must be an Integer pointer if it is provided.

If the target thread is in detached state, it is an error to join it.

Class

Function

Argument Type and Attributes

thread
TYPE(f_pthread_t), INTENT(IN)
ret
Integer pointer, INTENT(OUT), OPTIONAL

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following errors.

EDEADLK
This call will cause a deadlock, or the calling thread is trying to join itself.
EINVAL
The argument thread is invalid.
ESRCH
The argument thread designates a thread which does not exist or is in detached state.

f_pthread_key_create(key, dtr)

Purpose

This function can be used to acquire a thread-specific data key. The key will be returned in the argument key. The argument dtr is a subroutine that will be used to destruct the thread-specific data associated with this key when any thread terminates after this calling point. The destructor will receive the thread-specific data as its argument. The destructor itself is optional. If it is not provided, the system will not invoke any destructor on the thread-specific data associated with this key. Note that the number of thread-specific data keys is limited in each process. It is the user's responsibility to manage the usage of the keys. The per-process limit can be checked by the Fortran constant PTHREAD_DATAKEYS_MAX.

Class

Function

Argument Type and Attributes

key
TYPE(f_pthread_key_t), INTENT(OUT)
dtr
External, optional subroutine

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following errors.

EAGAIN
The maximum number of keys has been exceeded.
EINVAL
The argument key is invalid.
ENOMEM
There is insufficient memory to create this key.

f_pthread_key_delete(key)

Purpose

This function will destroy the thread-specific data key identified by the argument key. It is the user's responsibility to ensure that there is no thread-specific data associated with this key. This function does not call any destructor on the thread's behalf. After the key is destroyed, it can be reused by the system for f_pthread_key_create requests.

Class

Function

Argument Type and Attributes

key
TYPE(f_pthread_key_t), INTENT(INOUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following errors.

EINVAL
The argument key is invalid.
EBUSY
There is still data associated with this key.

f_pthread_key_t

Purpose

A derived data type whose components are all private. Any object of this type should be manipulated only through the appropriate interfaces provided in this module.

This data type corresponds to the POSIX pthread_key_t, which is the type of key object for accessing thread-specific data.

Class

Data Type

f_pthread_kill(thread, sig)

Purpose

This function can be used to send a signal to a target thread. The target thread is identified by argument thread. The signal which will be sent to the target thread is identified in argument sig. If sig contains value zero, error checking will be done by the system but no signal will be sent.

Class

Function

Argument Type and Attributes

thread
TYPE(f_pthread_t), INTENT(INOUT)
sig
INTEGER(4), INTENT(IN)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following errors.

EINVAL
The argument thread or sig is invalid.
ESRCH
The target thread does not exist.

f_pthread_mutex_destroy(mutex)

Purpose

This function should be called to destroy those mutex objects that are no longer required. In this way, the system can recollect the memory resources. The target mutex object is identified by the argument mutex.

Class

Function

Argument Type and Attributes

mutex
TYPE(f_pthread_mutex_t), INTENT(INOUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following errors.

EBUSY
The target mutex is locked or referenced by another thread.
EINVAL
The argument mutex is invalid.

f_pthread_mutex_init(mutex, mattr)

Purpose

This function can be used to initialize the mutex object identified by argument mutex. The initialized mutex will assume attributes set in the mutex attribute object mattr, if it is provided. If mattr is not provided, the system will initialize the mutex to have default attributes. After it is initialized, the mutex object can be used to synchronize accesses to critical data or code. It can also be used to build more complicated thread synchronization objects.

Another method to initialize mutex objects is to statically initialize them through the Fortran constant PTHREAD_MUTEX_INITIALIZER. If this method of initialization is used it is not necessary to call the function before using the mutex objects.

Class

Function

Argument Type and Attributes

mutex
TYPE(f_pthread_mutex_t), INTENT(OUT)
mattr
TYPE(f_pthread_mutexattr_t), INTENT(IN), OPTIONAL

Result Type and Attributes

INTEGER(4)

Result Value

This function always returns 0.

f_pthread_mutex_lock(mutex)

Purpose

This function can be used to acquire ownership of the mutex object. (In other words, the function will lock the mutex.) If the mutex has already been locked by another thread, the caller will wait until the mutex is unlocked. If the mutex is already locked by the caller itself, an error will be returned to prevent recursive locking.

Class

Function

Argument Type and Attributes

mutex
TYPE(f_pthread_mutex_t), INTENT(INOUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following errors.

EDEADLK
The mutex is locked by the calling thread already.
EINVAL
The argument mutex is invalid.

f_pthread_mutex_t

Purpose

A derived data type whose components are all private. Any object of this type should be manipulated through the appropriate interfaces provided in this module. In addition, objects of this type can be initialized statically through the Fortran constant PTHREAD_MUTEX_INITIALIZER.

This data type corresponds to the POSIX pthread_mutex_t, which is the type of mutex object.

Class

Data Type

f_pthread_mutex_trylock(mutex)

Purpose

This function can be used to acquire ownership of the mutex object. (In other words, the function will lock the mutex.) If the mutex has already been locked by another thread, the function returns the error code EBUSY. The calling thread can check the return code to take further actions. If the mutex is already locked by the caller itself, an error will be returned to prevent recursive locking.

Class

Function

Argument Type and Attributes

mutex
TYPE(f_pthread_mutex_t), INTENT(INOUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following errors.

EBUSY
The target mutex is locked or referenced by another thread.
EINVAL
The argument mutex is invalid.

f_pthread_mutex_unlock(mutex)

Purpose

This function releases the mutex object's ownership in order to allow other threads to lock the mutex.

Class

Function

Argument Type and Attributes

mutex
TYPE(f_pthread_mutex_t), INTENT(INOUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following errors.

EINVAL
The argument mutex is invalid.
EPERM
The mutex is not locked by the calling thread.

f_pthread_mutexattr_destroy(mattr)

Purpose

This function can be used to destroy a mutex attribute object that has been initialized previously. Allocated memory will then be recollected. A mutex created with this attribute will not be affected by this action.

Class

Function

Argument Type and Attributes

mattr
TYPE(f_pthread_mutexattr_t), INTENT(INOUT)

Result Type and Attributes

INTEGER(4)

Result Value

This function always returns 0.

f_pthread_mutexattr_getpshared(mattr, pshared)

Purpose

This function is used to query the process-shared attribute in the mutex attributes object identified by the argument mattr. The current setting of the attribute will be returned through the argument pshared.

Class

Function

Argument Type and Attributes

mattr
TYPE(f_pthread_mutexattr_t), INTENT(IN)
pshared

INTEGER(4), INTENT(IN)

On return from this function, psharedcontains one of the following values:

PTHREAD_PROCESS_SHARED
The mutex can be operated upon by any thread that has access to the memory where the mutex is allocated, even if the mutex is allocated in memory that is shared by multiple processes.
PTHREAD_PROCESS_PRIVATE
The mutex will only be operated upon by threads created within the same process as the thread that initialized the mutex.

Result Type and Attributes

INTEGER(4)

Result Value

If this function completes successfully, value 0 is returned and the value of the process-shared attribute is returned through the argument pshared. Otherwise, the following error will be returned:

EINVAL
The argument mattr is invalid.

f_pthread_mutexattr_gettype(mattr, type)

Purpose

This function is used to query the mutex type attribute in the mutex attributes object identified by the argument mattr.

If this function completes successfully, value 0 is returned and the type attribute will be returned through the argument type.

Class

Function

Argument Type and Attributes

mattr
TYPE(f_pthread_mutexattr_t), INTENT(IN)
type
INTEGER(4), INTENT(OUT)

On return from this function, type contains one of the following values:

PTHREAD_MUTEX_NORMAL
This type of mutex does not detect deadlock. A thread attempting to relock this mutex without first unlocking it will deadlock. Attempting to unlock a mutex locked by a different thread results in undefined behavior.
PTHREAD_MUTEX_ERRORCHECK
This type of mutex provides error checking. A thread attempting to relock this mutex without first unlocking it will return with an error. A thread attempting to unlock a mutex which another thread has locked will return an error. A thread attempting to unlock an unlocked mutex will return with an error.
PTHREAD_MUTEX_RECURSIVE
A thread attempting to relock this mutex without first unlocking it will succeed in locking the mutex. The relocking deadlock that can occur with mutexes of type PTHREAD_MUTEX_NORMAL cannot occur with this type of mutex. Multiple locks of this mutex require the same number of unlocks to release the mutex before another thread can acquire the mutex.

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The argument is invalid.

f_pthread_mutexattr_init(mattr)

Purpose

This function can be used to initialize a mutex attribute object before it can be used in any other way. The mutex attribute object will be returned through argument mattr.

Class

Function

Argument Type and Attributes

mattr
TYPE(f_pthread_mutexattr_t), INTENT(OUT)

Result Type and Attributes

INTEGER(4)

Result Value

This function returns 0.

f_pthread_mutexattr_setpshared(mattr, pshared)

Purpose

This function is used to set the process-shared attribute of the mutex attributes object identified by the argument mattr.

Class

Function

Argument Type and Attributes

mattr
TYPE(f_pthread_mutexattr_t), INTENT(INOUT)
pshared

INTEGER(4), INTENT(IN)

Must contain one of the following values:

PTHREAD_PROCESS_SHARED
Specifies the mutex can be operated upon by any thread that has access to the memory where the mutex is allocated, even if the mutex is allocated in memory that is shared by multiple processes.
PTHREAD_PROCESS_PRIVATE
Specifies the mutex will only be operated upon by threads created within the same process as the thread that initialized the mutex. This is the default setting of the attribute.

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The argument is invalid.

f_pthread_mutexattr_settype(mattr, type)

Purpose

This function is used to set the mutex type attribute in the mutex attributes object identified by the argument mattr The argument type identifies the mutex type attribute to be set.

Class

Function

Argument Type and Attributes

mattr
TYPE(f_pthread_mutexattr_t), INTENT(INOUT)
type
INTEGER(4), INTENT(IN)

Must contain one of the following values:

PTHREAD_MUTEX_NORMAL
This type of mutex does not detect deadlock. A thread attempting to relock this mutex without first unlocking it will deadlock. Attempting to unlock a mutex locked by a different thread results in undefined behavior.
PTHREAD_MUTEX_ERRORCHECK
This type of mutex provides error checking. A thread attempting to relock this mutex without first unlocking it will return with an error. A thread attempting to unlock a mutex which another thread has locked will return an error. A thread attempting to unlock an unlocked mutex will return with an error.
PTHREAD_MUTEX_RECURSIVE
A thread attempting to relock this mutex without first unlocking it will succeed in locking the mutex. The relocking deadlock that can occur with mutexes of type PTHREAD_MUTEX_NORMAL cannot occur with this type of mutex. Multiple locks of this mutex require the same number of unlocks to release the mutex before another thread can acquire the mutex.
PTHREAD_MUTEX_DEFAULT
The same as PTHREAD_MUTEX_NORMAL.

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
One of the arguments is invalid.

f_pthread_mutexattr_t

Purpose

A derived data type whose components are all private. Any object of this type should be manipulated only through the appropriate interfaces provided in this module.

This data type corresponds to the POSIX pthread_mutexattr_t, which is the type of mutex attribute object.

Class

Data Type

f_pthread_once(once, initr)

Purpose

This function can be used to initialize those data required to be initialized only once. The first thread calling this function will call initr to do the initialization. Other threads calling this function afterwards will have no effect. Argument initr must be a subroutine without dummy arguments.

Class

Function

Argument Type and Attributes

once
TYPE(f_pthread_once_t), INTENT(INOUT)
initr
A subroutine that has no dummy arguments.

Result Type and Attributes

INTEGER(4)

Result Value

This function returns 0.

f_pthread_once_t

Purpose

A derived data type whose components are all private. Any object of this type should be manipulated through the appropriate interfaces provided in this module. However, objects of this type can only be initialized through the Fortran constant PTHREAD_ONCE_INIT.

Class

Data Type

f_pthread_rwlock_destroy(rwlock)

Purpose

This function destroys the read-write lock object specified by the argument rwlock and releases any resources used by the lock.

Class

Function

Argument Type and Attributes

rwlock
TYPE(f_pthread_rwlock_t), INTENT(INOUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following errors.

EBUSY
The target read-write object is locked.

f_pthread_rwlock_init(rwlock, rwattr)

Purpose

This function initializes the read-write lock object specified by rwlock with the attribute specified by the argument rwattr. If the optional argument rwattr is not provided, the system will initialize the read-write lock object with the default attributes. After it is initialized, the lock can be used to synchronize access to critical data. With a read-write lock, many threads can have simultaneous read-only access to data, while only one thread can have write access at any given time and no other readers or writers are allowed.

Another method to initialize read-write lock objects is to statically initialize them through the Fortran constant PTHREAD_RWLOCK_INITIALIZER. If this method of initialization is used, it is not necessary to call this function before using the read-write lock objects.

Class

Function

Argument Type and Attributes

rwlock
TYPE(f_pthread_rwlock_t), INTENT(OUT)
rwattr
TYPE(f_pthread_rwlockattr_t), INTENT(IN), OPTIONAL

Result Type and Attributes

INTEGER(4)

Result Value

This function returns 0.

f_pthread_rwlock_rdlock(rwlock)

Purpose

This function applies a read lock to the read-write lock specified by the argument rwlock. The calling thread acquires the read lock if a writer does not hold the lock and there are no writes blocked on the lock. Otherwise, the calling thread will not acquire the read lock. If the read lock is not acquired, the calling thread blocks (that is, it does not return from the f_pthread_rwlock_rdlock call) until it can acquire the lock. Results are undefined if the calling thread holds a write lock on rwlock at the time the call is made. A thread may hold multiple concurrent read locks on rwlock (that is, successfully call the f_pthread_rwlock_rdlock function n times). If so, the thread must perform matching unlocks (that is, it must call the f_pthread_rwlock_unlock function n times).

Class

Function

Argument Type and Attributes

rwlock
TYPE(f_pthread_rwlock_t), INTENT(INOUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following errors.

EAGAIN
The read-write lock could not be acquired because the maximum number of read locks for rwlock has been exceeded.
EINVAL
The argument rwlock does not refer to an initialized read-write lock object.

f_pthread_rwlock_t

Purpose

A derived data type whose components are all private. Any object of this type should be manipulated only through the appropriate interfaces provided in this module. In addition, objects of this type can be initialized statically through the Fortran constant PTHREAD_RWLOCK_INITIALIZER.

Class

Data Type

f_pthread_rwlock_tryrdlock(rwlock)

Purpose

This function applies a read lock like the f_pthread_rwlock_rdlock function with the exception that the function fails if any thread holds a write lock on rwlock or there are writers blocked on rwlock. In that case, the function returns EBUSY. The calling thread can check the return code to take further actions.

Class

Function

Argument Type and Attributes

rwlock
TYPE(f_pthread_rwlock_t), INTENT(INOUT)

Result Type and Attributes

INTEGER(4)

Result Value

This function returns zero if the lock for reading on the read-write lock object specified by rwlock is acquired. Otherwise, the following error will be returned:

EBUSY
The read-write lock could not be acquired for reading because a writer holds the lock or was blocked on it.

f_pthread_rwlock_trywrlock(rwlock)

Purpose

This function applies a write lock like the f_pthread_rwlock_wrlock function with the exception that the function fails if any thread currently holds rwlock (for reading or writing). In that case, the function returns EBUSY. The calling thread can check the return code to take further actions.

Class

Function

Argument Type and Attributes

rwlock
TYPE(f_pthread_rwlock_t), INTENT(INOUT)

Result Type and Attributes

INTEGER(4)

Result Value

This function returns zero if the lock for writing on the read-write lock object specified by rwlock is acquired. Otherwise, the following error will be returned:

EBUSY
The read-write lock could not be acquired for writing because it is already locked for reading or writing.

f_pthread_rwlock_unlock(rwlock)

Purpose

This function is used to release a lock held on the read-write lock object specified by the argument rwlock. If this function is called to release a read lock from the read-write lock object and there are other read locks currently held on this read-write lock object, the read-write lock object remains in the read locked state. If this function releases the calling thread's last read lock on this read-write lock object, then the calling thread is no longer one of the owners of the object. If this function releases the last read lock for this read-write lock object, the read-write lock object will be put in the unlocked state with no owners.

Class

Function

Argument Type and Attributes

rwlock
TYPE(f_pthread_rwlock_t), INTENT(INOUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following errors.

EPERM
The current thread does not own the read-write lock.

f_pthread_rwlock_wrlock(rwlock)

Purpose

This function applies a write lock to the read-write lock specified by the argument rwlock. The calling thread acquires the write lock if no other thread (reader or writer) holds the read-write lock rwlock. Otherwise, the thread blocks (that is, does not return from the f_pthread_rwlock_wrlock call) until it acquires the lock. Results are undefined if the calling thread holds the read-write lock (whether a read or write lock) at the time the call is made.

Class

Function

Argument Type and Attributes

rwlock
TYPE(f_pthread_rwlock_t), INTENT(INOUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The argument rwlock does not refer to an initialized read-write lock object.

f_pthread_rwlockattr_destroy(rwattr)

Purpose

This function destroys a read-write lock attributes object specified by the argument rwattr which has been initialized previously. A read-write lock created with this attribute will not be affected by the action.

Class

Function

Argument Type and Attributes

rwattr
TYPE(f_pthread_rwlockattr_t), INTENT(INOUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The argument rwattr is invalid.

f_pthread_rwlockattr_getpshared(rwattr, pshared)

Purpose

This function is used to obtain the value of the process-shared attribute from the initialized read-write lock attributes object specified by the argument rwattr. The current setting of this attribute will be returned in the argument pshared. pshared will contain one of the following values:

Class

Function

Argument Type and Attributes

rwattr
TYPE(f_pthread_rwlockattr_t), INTENT(IN)
pshared
INTEGER(4), INTENT(OUT)

On return from this function, the value of pshared will be one of the following:

PTHREAD_PROCESS_SHARED
The read-write lock can be operated upon by any thread that has access to the memory where it is allocated, even if these threads belong to different processes.
PTHREAD_PROCESS_PRIVATE
The read-write lock shall only be used by threads within the same process as the thread that created it.

Result Type and Attributes

INTEGER(4)

Result Value

If this function completes successfully, value 0 is returned and the value of the process-shared attribute of rwattr is stored into the object specified by the argument pshared. Otherwise, the following error will be returned:

EINVAL
The argument rwattr is invalid.

f_pthread_rwlockattr_init(rwattr)

Purpose

This function initializes a read-write lock attributes object specified by rwattr with the default value for all of the attributes.

Class

Function

Argument Type and Attributes

rwattr
TYPE(f_pthread_rwlockattr_t), INTENT(OUT)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

ENOMEM
There is insufficient memory to initialize the read-write lock attributes object.

f_pthread_rwlockattr_setpshared(rwattr, pshared)

Purpose

This function is used to set the process-shared attribute in an initialized read-write lock attributes object specified by the argument rwattr.

Class

Function

Argument Type and Attributes

rwattr
TYPE(f_pthread_rwlockattr_t), INTENT(INOUT)
pshared
INTEGER(4), INTENT(IN)

Must be one of the following:

PTHREAD_PROCESS_SHARED
Specifies the read-write lock can be operated upon by any thread that has access to the memory where it is allocated, even if these threads belong to different processes.
PTHREAD_PROCESS_PRIVATE
Specifies the read-write lock shall only be used by threads within the same process as the thread that created it. This is the default setting of the attribute.

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following errors.

EINVAL
The argument rwattr is invalid.
ENOSYS
The value of pshared is equal to pthread_process_shared.

f_pthread_rwlockattr_t

Purpose

This is a derived data type whose components are all private. Any object of this type should be manipulated only through the appropriate interfaces provided in this module.

Class

Data Type

f_pthread_self()

Purpose

This function can be used to return the thread ID of the calling thread.

Class

Function

Argument Type and Attributes

None

Result Type and Attributes

TYPE(f_pthread_t)

Result Value

The calling thread's ID is returned.

f_pthread_setcancelstate(state, oldstate)

Purpose

This function can be used to set the thread's cancelability state. The new state will be set according to the argument state. The old state will be returned in the argument oldstate.

Class

Function

Argument Type and Attributes

state
INTEGER(4), INTENT(IN)

Must contain one of the following:

PTHREAD_CANCEL_DISABLE:
the thread's cancelability is disabled.
PTHREAD_CANCEL_ENABLE:
the thread's cancelability is enabled.
oldstate
INTEGER(4), INTENT(OUT)

On return from this function, oldstate will contain one of the following values:

PTHREAD_CANCEL_DISABLE:
the thread's cancelability is disabled.
PTHREAD_CANCEL_ENABLE:
the thread's cancelability is enabled.

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The argument state is invalid.

f_pthread_setcanceltype(type, oldtype)

Purpose

This function can be used to set the thread's cancelability type. The new type will be set according to the argument type. The old type will be returned in argument oldtype.

Class

Function

Argument Type and Attributes

type
INTEGER(4), INTENT(IN)

Must contain one of the following values:

PTHREAD_CANCEL_DEFERRED:
cancelation request will be delayed until a cancelation point.
PTHREAD_CANCEL_ASYNCHRONOUS:
cancelation request will be acted upon immediately. This may cause unexpected results.
oldtype
INTEGER(4), INTENT(OUT)

On return from this procedure, oldtype will contain one of the following values:

PTHREAD_CANCEL_DEFERRED:
cancelation request will be delayed until a cancelation point.
PTHREAD_CANCEL_ASYNCHRONOUS:
cancelation request will be acted upon immediately. This may cause unexpected results.

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns the following error.

EINVAL
The argument type is invalid.

f_pthread_setconcurrency(new_level)

Purpose

This function is used to inform the pthreads library implementation of desired concurrency level as specified by the argument new_level. The actual level of concurrency provided by the implementation as a result of this function call is unspecified.

Class

Function

Argument Type and Attributes

new_level
INTEGER(4), INTENT(IN)

Result Type and Attributes

INTEGER(4)

Result Value

This function returns 0.

f_pthread_setschedparam(thread, policy, param)

Purpose

This function can be used to dynamically set the scheduling policy and the scheduling property of a thread. The target thread is identified by argument thread. The new scheduling policy for the target thread is provided through argument policy. The new scheduling property of the target thread will be set to the value provided by argument param. The sched_priority field in param defines the scheduling priority. Its range is 1-127.

Class

Function

Argument Type and Attributes

thread
TYPE(f_pthread_t), INTENT(INOUT)
policy
INTEGER(4), INTENT(IN)
param
TYPE(f_sched_param), INTENT(IN)

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following errors

ENOSYS
The POSIX priority scheduling option is not implemented on Linux.
ENOTSUP
The value of argument policy or param is not supported.
EPERM
The target thread is not permitted to perform the operation or is in a mutex protocol already.
ESRCH
The target thread does not exist or is invalid.

f_pthread_setspecific(key, arg)

Purpose

This function can be used to set the calling thread's specific data associated with the key identified by argument key. The argument arg, which is optional, identifies the thread-specific data to be set. If arg is not provided, the thread-specific data will be set to NULL, which is the initial value for each thread. Only an Integer pointer can be passed as the arg argument. If arg is not an Integer pointer, the result is undefined.

The actual argument arg must be a variable, and consequently eligible as a left-value in an assignment statement. If you pass an array section with vector subscripts to the argument arg, the result is unpredictable.

Class

Function

Argument Type and Attributes

key
TYPE(f_pthread_key_t), INTENT(IN)
arg
Integer pointer, INTENT(IN), OPTIONAL

Result Type and Attributes

INTEGER(4)

Result Value

On successful completion, this function returns 0. Otherwise, this function returns one of the following errors

EINVAL
The argument key is invalid.
ENOMEM
There is insufficient memory to associate the data with the key.

f_pthread_t

Purpose

A derived data type whose components are all private. Any object of this type should be manipulated only through the appropriate interfaces provided in this module.

This data type corresponds to the POSIX pthread_t, which is the type of thread object.

Class

Data Type

f_pthread_testcancel()

Purpose

This subroutine provides a cancelation point in a thread. When it is called, any pending cancelation request will be acted upon immediately if it is in the enabled state.

Class

Subroutine

Argument Type and Attributes

None

Result Type and Attributes

None

f_sched_param

Purpose

This data type corresponds to the Linux system data structure sched_param, which is a system data type.

This is a public data structure defined as:

type f_sched_param
  sequence
  integer sched_priority
end type f_sched_param

Class

Data Type

f_sched_yield()

Purpose

This function is used to force the calling thread to relinquish the processor until it again becomes the head of its thread list.

Class

Function

Argument Type and Attributes

None.

Result Type and Attributes

INTEGER(4)

Result Value

If this function completes successfully, value 0 is returned. Otherwise, a value of -1 will be returned.

f_timespec

Purpose

This is a Fortran definition of the Linux system data structure timespec. Within the Fortran Pthreads module, objects of this type are used to specify an absolute date and time. This deadline absolute date is used when waiting on a POSIX condition variable.

In 32-bit mode, f_timespec is defined as:

TYPE F_Timespec
    SEQUENCE
    INTEGER(4) tv_sec
    INTEGER(KIND=REGISTER_SIZE) tv_nsec
END TYPE F_Timespec

In 64-bit mode, f_timespec is defined as:

TYPE F_Timespec
    SEQUENCE
    INTEGER(4) tv_sec
    INTEGER(4) pad
    INTEGER(KIND=REGISTER_SIZE) tv_nsec
END TYPE F_Timespec

Class

Data Type

End of IBM Extension