|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Table 18. Fortran Pthreads Library Module
Functions, Subroutines, and Data Structures |
---|
f_maketime
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. Return Value: The absolute time, which is delay seconds from the calling moment, is returned. Example: type(f_timespec) function f_maketime(delay) integer(4), intent(in):: delay end function |
f_pthread_attr_destroy
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. Return Codes: If errors are detected during the execution of this function, the following error code will be returned:
Example:
integer function f_pthread_attr_destroy(attr) type(f_pthread_attr_t), intent(inout):: attr end function |
f_pthread_attr_getdetachstate
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. Argument detach will contain one of the following values:
For more information about these thread states, refer to the AIX Operating System documentation. Return Codes: If errors are detected during the execution of this function, the following error code will be returned:
Example:
integer function f_pthread_attr_getdetachstate(attr, detach) type(f_pthread_attr_t), intent(in):: attr integer(4), intent(out):: detach end function |
f_pthread_attr_getguardsize
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. Return Codes: If this function completes successfully, value 0 is returned. Otherwise, the following error will be returned: EINVAL The argument attr is invalid. Example:
integer(4) function f_pthread_attr_getguardsize(attr, guardsize) type(f_pthread_attr_t), intent(in):: attr integer(kind=REGISTER_SIZE), intent(out):: guardsize end function f_pthread_attr_getguardsize |
f_pthread_attr_getinheritsched
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. Argument inherit will contain one of the following values:
Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_attr_getinheritsched(attr, inherit) type(f_pthread_attr_t), intent(in):: attr integer(4), intent(out):: inherit end function |
f_pthread_attr_getschedparam
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. See the AIX system documentation for more information on the scheduling property setting. Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_attr_getschedparam(attr, param) type(f_pthread_attr_t), intent(in):: attr type(f_sched_param), intent(out):: param end function |
f_pthread_attr_getschedpolicy
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. The valid scheduling policies on AIX can be found in the AIX Operating System documentation. Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_attr_getschedpolicy(attr, policy) type(f_pthread_attr_t), intent(in):: attr integer(4), intent(out):: policy |
f_pthread_attr_getscope
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. Argument scope will contain one of the following values:
Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_attr_getscope(attr, scope) type(f_pthread_attr_t), intent(in):: attr integer(4), intent(out):: scope end function |
f_pthread_attr_getstackaddr
This function is used to get the stackaddrattribute in the thread attribute object attr. The current setting of the attribute will be returned through the argument stackaddr. The type of the argument stackaddr is integer pointer. The stackaddr attribute specifies the stack address of a thread created with this attributes object. Return Codes: If this function completes successfully, value 0 is returned. Otherwise, the following error will be returned: EINVAL The argument attr is invalid. Example:
integer(4) function f_pthread_attr_getstackaddr(attr, stackaddr) type(f_pthread_attr_t), intent(in):: attr integer(4) int_template pointer (stackaddr, int_template) intent(out) stackaddr end function f_pthread_attr_getstackaddr |
f_pthread_attr_getstacksize
This function can be used to query the current stack size attribute setting in the attribute object attr. If this function executes successfully, the stack size in bytes will be returned in argument ssize. Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_attr_getstacksize(attr, ssize) type(f_pthread_attr_t), intent(in):: attr integer(4), intent(out):: ssize end function |
f_pthread_attr_init
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. Refer to the AIX Operating System documentation for more information on the default attributes. Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_attr_init(attr) type(f_pthread_attr_t), intent(out):: attr end function |
f_pthread_attr_setdetachstate
This function can be used to set the detach state attribute in the thread attribute object attr. Argument detach must contain one of the following values:
For more information about these thread states, refer to the AIX Operating System documentation. Return Codes: If errors are detected during the execution of this function, the following error code will be returned:
Example:
integer function f_pthread_attr_setdetachstate(attr, detach) type(f_pthread_attr_t), intent(inout):: attr integer(4), intent(in):: detach end function |
f_pthread_attr_setguardsize
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 sizeguardsizebytes is provided for each thread created withattr. For more information about guardsize, refer to the AIX Operating System documentation. Return Codes: If this function completes successfully, value 0 is returned. Otherwise, one of the following errors will be returned: EINVAL The argument attr is invalid. EINVAL The argument guardsize is invalid. Example:
integer(4) function f_pthread_attr_setguardsize(attr, guardsize) type(f_pthread_attr_t), intent(inout):: attr integer(kind=REGISTER_SIZE), intent(in):: guardsize end function f_pthread_attr_setguardsize |
f_pthread_attr_setinheritsched
This function can be used to set the inheritance attribute of the thread scheduling property in the thread attribute object attr. Argument inherit must contain one of the following values:
Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_attr_setinheritsched(attr, inherit) type(f_pthread_attr_t), intent(inout):: attr integer(4), intent(in):: inherit end function |
f_pthread_attr_setschedparam
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. Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_attr_setschedparam(attr, param) type(f_pthread_attr_t), intent(inout):: attr type(f_sched_param), intent(in):: param end function |
f_pthread_attr_setschedpolicy
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. Argument policy must contain one of the following constants:
Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_attr_setschedpolicy(attr, policy) type(f_pthread_attr_t), intent(inout):: attr integer(4), intent(in):: policy end function |
f_pthread_attr_setscope
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:
Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_attr_setscope(attr, scope) type(f_pthread_attr_t), intent(inout):: attr integer(4), intent(in):: scope end function |
f_pthread_attr_setstackaddr
This function is used to set the stackaddr attribute in the thread attributes object attr. The new value of this attribute is obtained from the argument stackaddr. The type of the argument stackaddris integer pointer. The stackaddr attribute specifies the stack address of a thread created with this attributes object. Return Codes: If this function completes successfully, value 0 is returned. Otherwise, the following error will be returned: EINVAL The argument attr is invalid. Example:
integer(4) function f_pthread_attr_setstackaddr(attr, stackaddr) type(f_pthread_attr_t), intent(inout):: attr integer(4) int_template pointer (stackaddr, int_template) intent(in) stackaddr end function f_pthread_attr_setstackaddr |
f_pthread_attr_setstacksize
This function can be used to set the stack size attribute in the pthread attribute object attr. Argument ssize is an integer indicating the stack size desired in bytes. When a thread is created using this attribute object, the system will allocate a minimum stack size of ssize bytes. Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_attr_setstacksize(attr, ssize) type(f_pthread_attr_t), intent(inout):: attr integer(4), intent(in):: ssize end function |
f_pthread_attr_t
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. |
f_pthread_cancel
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. For more information about thread cancelation and concerns about security, refer to the AIX Operating System documentation. Return Codes: If errors are detected during the execution of this function, the following error code will be returned:
Example:
integer function f_pthread_cancel(thread) type(f_pthread_t), intent(inout):: thread end function |
f_pthread_cleanup_pop
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. Return Codes: There is no return value from this subroutine. Example:
subroutine f_pthread_cleanup_pop(exec) integer(4), intent(in):: exec end subroutine |
f_pthread_cleanup_push
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. Note that argument arg is a generic argument which can be of any type and any rank. 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. Argument flag can assume a value that is one of, or a combination of, the following constants:
Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_cleanup_push(cleanup, flag, arg) external cleanup integer(4), intent(in):: flag end function |
f_pthread_cond_broadcast
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. Return Codes: If errors are detected during the execution of this function, the following error code will be returned:
Example:
integer function f_pthread_cond_broadcast(cond) type(f_pthread_cond_t), intent(inout):: cond end function |
f_pthread_cond_destroy
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. For more information about thread synchronization and condition variable usage, refer to the AIX Operating System documentation. Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_cond_destroy(cond) type(f_pthread_cond_t), intent(inout):: cond end function |
f_pthread_cond_init
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. For more information about thread synchronization and condition variable usage, refer to the AIX Operating System documentation. Another method of initializing a condition variable is to initialize it statically using the Fortran constant PTHREAD_COND_INITIALIZER. Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_cond_init(cond, cattr) type(f_pthread_cond_t), intent(out):: cond type(f_pthread_condattr_t), intent(in), optional:: cattr end function |
f_pthread_cond_signal
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. For more information about thread synchronization and condition variable usage, refer to the AIX Operating System documentation. Return Codes: If errors are detected during the execution of this function, the following error code will be returned:
Example:
integer function f_pthread_cond_signal(cond) type(f_pthread_cond_t), intent(inout):: cond end function |
f_pthread_cond_t
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. |
f_pthread_cond_timedwait
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. For information on the absolute date, refer to the AIX Operating System documentation. Return Codes: If errors are detected during the execution of this function, one of the following error codes is returned:
Example:
integer function f_pthread_cond_timedwait(cond, mutex, timeout) type(f_pthread_cond_t), intent(inout):: cond type(f_pthread_mutex_t), intent(inout):: mutex type(f_timespec), intent(in):: timeout end function |
f_pthread_cond_wait
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. Return Codes: When this function executes successfully, the mutex is locked again before the function returns. If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_cond_wait(cond, mutex) type(f_pthread_cond_t), intent(inout):: cond type(f_pthread_mutex_t), intent(inout):: mutex end function |
f_pthread_condattr_destroy
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. Return Codes: If errors are detected during the execution of this function, the following error code will be returned:
Example:
integer function f_pthread_condattr_destroy(cattr) type(f_pthread_condattr_t), intent(inout):: cattr end function |
f_pthread_condattr_getpshared
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. pshared will contain one of the following values:
Return Codes: 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 cattr is invalid. Example:
integer(4) function f_pthread_condattr_getpshared(cattr, pshared) type(f_pthread_condattr_t), intent(in):: cattr integer(4), intent(out):: pshared end function f_pthread_condattr_getpshared |
f_pthread_condattr_setpshared
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. pshared must have one of the following values:
Return Codes: If this function completes successfully, value 0 is returned. Otherwise, one of the following errors will be returned: EINVAL The argument cattr is invalid. EINVAL The value specified by the argument pshared is invalid. Example:
integer(4) function f_pthread_condattr_setpshared(cattr, pshared) type(f_pthread_condattr_t), intent(inout):: cattr integer(4), intent(in):: pshared end function f_pthread_condattr_setpshared |
f_pthread_condattr_t
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. |
f_pthread_create
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 flagis 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. Note that argument arg is a generic argument which can be of any type and any rank. The argument flag must be used to convey the property of the argument arg exactly to the system. The argument flag can assume a value which is one of, or a combination of, the following constants:
Return Codes: If the call to this function is successful, the ID of the newly created thread will be returned through argument thread. Otherwise, one of the following error codes will be returned:
Example:
integer function f_pthread_create(thread, attr, flag, ent, arg) type(f_pthread_t), intent(out):: thread type(f_pthread_attr_t), intent(in), optional:: attr integer(4), intent(in):: flag external ent end function |
f_pthread_detach
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. Return Codes: If this function completes successfully, value 0 is returned. Otherwise, the following error will be returned: EINVAL The argument thread is invalid. Example:
integer(4) function f_pthread_detach(thread) type(f_pthread_t), intent(in):: thread end function f_pthread_detach |
f_pthread_equal
This function can be used to compare whether two thread ID's identify the same thread or not. Return Codes:
Example:
logical function f_pthread_equal(thread1, thread2) type(f_pthread_t), intent(in):: thread1, thread2 end function |
f_pthread_exit
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. Return Codes: This subroutine never returns. If argument ret is not provided, NULL will be provided as this thread's exit status. Example:
subroutine f_pthread_exit(ret) pointer(ret, byte) optional ret intent(in) ret end subroutine |
f_pthread_getconcurrency
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. For more information about the concurrency level, refer to the AIX Operating System documentation. Example:
integer(4) function f_pthread_getconcurrency() end function f_pthread_getconcurrency |
f_pthread_getschedparam
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. Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_getschedparam(thread, policy, param) type(f_pthread_t), intent(in):: thread integer(4), intent(out):: policy type(f_sched_param), intent(out):: param end function |
f_pthread_getspecific
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. If there is no data associated with the key for the calling thread, NULL will be returned. Currently, arg must be an integer pointer. If it is not an integer pointer, the result is undefined. Return Codes: If errors are detected during the execution of this function, the following error code will be returned:
Example:
integer function f_pthread_getspecific(key, arg) type(f_pthread_key_t), intent(in):: key pointer(arg, byte) intent(out) arg end function |
f_pthread_join
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. Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_join(thread, ret) type(f_pthread_t), intent(in):: thread optional ret intent(out) ret pointer(ret, byte) end function |
f_pthread_key_create
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. Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_key_create(key, dtr) type(f_pthread_key_t), intent(out):: key external dtr optional dtr end function |
f_pthread_key_delete
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. Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_key_delete(key) type(f_pthread_key_t), intent(inout):: key end function |
f_pthread_key_t
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. |
f_pthread_kill
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. For more information about signal management in multi-threaded systems, refer to the AIX Operating System documentation. Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_kill(thread, sig) type(f_pthread_t), intent(inout):: thread integer(4), intent(in):: sig end function |
f_pthread_mutex_destroy
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. Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_mutex_destroy(mutex) type)f_pthread_mutex_t), intent(inout):: mutex end function |
f_pthread_mutex_getprioceiling
This function can be used to dynamically query the priority ceiling attribute of the mutex object identified by the argument mutex. The current ceiling value will be returned through the argument old. Return Codes: Note that this function cannot be used at present since mutex priority protection protocol is not implemented on AIX. Example:
integer function f_pthread_mutex_getprioceiling(mutex, old) type(f_pthread_mutex_t), intent(in):: mutex integer(4), intent(out):: old end function |
f_pthread_mutex_init
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. Return Codes: If errors occur in the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_mutex_init(mutex, mattr) type(f_pthread_mutex_t), intent(out):: mutex type(f_pthread_mutexattr_t), intent(in), optional:: mattr end function |
f_pthread_mutex_lock
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. Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_mutex_lock(mutex) type(f_pthread_mutex_t), intent(inout):: mutex end function |
f_pthread_mutex_setprioceiling
This function can be used to dynamically set the priority ceiling attribute of the mutex object identified by the argument mutex. The new ceiling will be set to the value contained in the argument new. The previous ceiling will be returned through the argument old. The argument new should assume an integer value with a range from 1 to 127. Return Codes: Note that this function cannot be used at present since mutex priority protection protocol is not implemented on AIX. Example:
integer function f_pthread_mutex_setprioceiling(mutex, new, old) type(f_pthread_mutex_t), intent(inout):: mutex integer(4), intent(in):: new integer(4), intent(out):: old end function |
f_pthread_mutex_t
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. |
f_pthread_mutex_trylock
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. Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_mutex_trylock(mutex) type(f_pthread_mutex_t), intent(inout):: mutex end function |
f_pthread_mutex_unlock
This function should be called to release the mutex object's ownership as soon as possible in order to allow other threads to lock the mutex. Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_mutex_unlock(mutex) type(f_pthread_mutex_t), intent(inout):: mutex end function |
f_pthread_mutexattr_destroy
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. Return Codes: If errors are detected during the execution of this function, the following error code will be returned:
Example:
integer function f_pthread_mutexattr_destroy(mattr) type(f_pthread_mutexattr_t), intent(inout):: mattr end function |
f_pthread_mutexattr_getprioceiling
This function can be used to query the mutex priority ceiling attribute in the mutex attribute object identified by argument mattr. The ceiling attribute will be returned through argument ceiling. Return Codes: Note that this function cannot be used at present since the mutex priority protection protocol is not implemented on AIX. Example:
integer function f_pthread_mutexattr_getprioceiling(mattr, ceiling) type(f_pthread_mutexattr_t), intent(in):: mattr integer(4), intent(out):: ceiling end function |
f_pthread_mutexattr_getprotocol
This function can be used to query the current setting of mutex protocol attribute in the mutex attribute object identified by argument mattr. The protocol attribute will be returned through argument proto. Return Codes: Note that this function cannot be used at present since mutex priority inheritance and priority protection are not implemented on AIX. Example:
integer function f_pthread_mutexattr_getprotocol(mattr, proto) type(f_pthread_mutexattr_t), intent(in):: mattr integer(4), intent(out):: proto end function |
f_pthread_mutexattr_getpshared
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. pshared will contain one of the following values:
Return Codes: 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. Example:
integer(4) function f_pthread_mutexattr_getpshared(mattr, pshared) type(f_pthread_mutexattr_t), intent(in):: mattr integer(4), intent(out):: pshared end function f_pthread_mutexattr_getpshared |
f_pthread_mutexattr_gettype
This function is used to query the mutex type attribute in the mutex attributes object identified by the argumentmattr. If this function completes successfully, value 0 is returned and the type attribute will be returned through the argument type. The argument type will contain one of the following values:
Return Codes: If this function fails, the following error will be returned: EINVAL The argument mattr is invalid. Example:
integer(4) function f_pthread_mutexattr_gettype(mattr, type) type(f_pthread_mutexattr_t), intent(in):: mattr integer(4), intent(out):: type end function f_pthread_mutexattr_gettype |
f_pthread_mutexattr_init
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. Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_mutexattr_init(mattr) type(f_pthread_mutexattr_t), intent(out):: mattr end function |
f_pthread_mutexattr_setprioceiling
This function can be used to set the mutex priority ceiling attribute in the mutex attribute object identified by the argument mattr. Argument ceiling is an integer with a range from 1 to 127. This attribute has an effect only if the mutex priority protection protocol is used. Return Codes: Note that this function cannot be used at present since the priority protection protocol is not implemented on AIX. Example:
integer function f_pthread_mutexattr_setprioceiling(mattr, ceiling) type(f_pthread_mutexattr_t), intent(inout):: mattr integer(4), intent(in):: ceiling end function |
f_pthread_mutexattr_setprotocol
This function can be used to set the mutex protocol attribute in the mutex attribute object identified by argument mattr. Argument proto identifies the mutex protocol to be set. For more information about the set of valid values for proto, refer to the AIX Operating System documentation. Return Codes: Note that this function cannot be used at present since mutex priority inheritance and priority protection are not implemented on AIX. Example:
integer function f_pthread_mutexattr_setprotocol(mattr, proto) type(p_thread_mutexattr_t), intent(inout):: mattr integer(4), intent(in):: proto end function |
f_pthread_mutexattr_setpshared
This function is used to set the process-shared attribute of the mutex attributes object identified by the argument mattr. The argument pshared must have one of the following values:
Return Codes: If this function completes successfully, value 0 is returned. Otherwise, one of the following errors will be returned: EINVAL The argument mattr is invalid. EINVAL The value specified by the argument pshared is invalid. Example:
integer(4) function f_pthread_mutexattr_setpshared(mattr, pshared) type(f_pthread_mutexattr_t), intent(inout):: mattr integer(4), intent(in):: pshared end function f_pthread_mutexattr_setpshared |
f_pthread_mutexattr_settype
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. For more information about the type of a mutex, refer to the AIX Operating System documentation. The argument type must contain one of the following values:
Return Codes: If this function completes successfully, value 0 is returned. Otherwise, one of the following errors will be returned: EINVAL The value of type is invalid. EINVAL The argument mattr is invalid. Example:
integer(4) function f_pthread_mutexattr_settype(mattr, type) type(f_pthread_mutexattr_t), intent(inout):: mattr integer(4), intent(in):: type end function f_pthread_mutexattr_settype |
f_pthread_mutexattr_t
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. |
f_pthread_once
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. Return Codes: If errors are detected during the execution of this function, the following error code will be returned:
Example:
integer function f_pthread_once(once, initr) type(f_pthread_once_t), intent(inout):: once external initr end function |
f_pthread_once_t
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. This data type corresponds to the POSIX pthread_once_t, which is the type of once-block object. |
f_pthread_rwlock_destroy
This function destroys the read-write lock object specified by the argument rwlock and releases any resources used by the lock. Return Codes: If this function completes successfully, value 0 is returned. Otherwise, one of the following errors will be returned: EBUSY The target read-write lock object is locked. EINVAL The argument rwlock is invalid. Example:
integer(4) function f_pthread_rwlock_destroy(rwlock) type(f_pthread_rwlock_t), intent(inout):: rwlock end function f_pthread_rwlock_destroy |
f_pthread_rwlock_init
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. For more information about thread synchronization and read-write lock usage, refer to the AIX Operating System documentation. 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. Return Codes: If this function completes successfully, value 0 is returned. Otherwise, one of the following errors will be returned: EAGAIN The system did not have enough resources to initialize this read-write lock. ENOMEM There is insufficient memory to initialize this read-write lock. EBUSY This read-write lock is already in use. It was initialized and not yet destroyed. EINVAL The argument rwlock or rwattr is invalid. EPERM The caller does not have privilege to perform the operation. Example:
integer(4) function f_pthread_rwlock_init(rwlock, rwattr) type(f_pthread_rwlock_t), intent(out):: rwlock type(f_pthread_rwlockattr_t), intent(in), optional:: rwattr end function f_pthread_rwlock_init |
f_pthread_rwlock_rdlock
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. If a writer holds the lock, 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). Return Codes: If this function completes successfully, value 0 is returned. Otherwise, one of the following errors will be returned: EINVAL The argument rwlock does not refer to an initialized read-write lock object. EAGAIN The read-write lock could not be acquired because the maximum number of read locks for rwlock has been exceeded. Example:
integer(4) function f_pthread_rwlock_rdlock(rwlock) type(f_pthread_rwlock_t), intent(inout):: rwlock end function f_pthread_rwlock_rdlock |
f_pthread_rwlock_t
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. This data type corresponds to the AIX 4.3 data type pthread_rwlock_t, which is the type of the read-write lock objects. |
f_pthread_rwlock_tryrdlock
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. Return Codes: This function returns zero if the lock for reading on the read-write lock object specified by rwlock is acquired. Otherwise, one of the following errors will be returned: EINVAL The argument rwlock does not refer to an initialized read-write lock object. EBUSY The read-write lock could not be acquired for reading because a writer holds the lock or was blocked on it. EAGAIN The read-write lock could not be acquired because the maximum number of read locks for rwlock has been exceeded. EDEADLK The current thread already owns the read-write lock for writing. Example:
integer(4) function f_pthread_rwlock_tryrdlock(rwlock) type(f_pthread_rwlock_t), intent(inout):: rwlock end function f_pthread_rwlock_tryrdlock |
f_pthread_rwlock_trywrlock
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. Return Codes: This function returns zero if the lock for writing on the read-write lock object specified by rwlock is acquired. Otherwise, one of the following errors will be returned: EINVAL The argument rwlock does not refer to an initialized read-write lock object. EBUSY The read-write lock could not be acquired for writing because it was already locked for reading or writing. EDEADLK The current thread already owns the read-write lock for writing or reading. Example:
integer(4) function f_pthread_rwlock_trywrlock(rwlock) type(f_pthread_rwlock_t), intent(inout):: rwlock end function f_pthread_rwlock_trywrlock |
f_pthread_rwlock_unlock
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. Return Codes: If this function completes successfully, value 0 is returned. Otherwise, one of the following errors will be returned: EINVAL The argument rwlock does not refer to an initialized read-write lock object. EPERM The current thread does not own the read-write lock. Example:
integer(4) function f_pthread_rwlock_unlock(rwlock) type(f_pthread_rwlock_t), intent(inout):: rwlock end function f_pthread_rwlock_unlock |
f_pthread_rwlock_wrlock
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. Return Codes: If this function completes successfully, value 0 is returned. Otherwise, the following error will be returned: EINVAL The argument rwlock does not refer to an initialized read-write lock object. Example:
integer(4) function f_pthread_rwlock_wrlock(rwlock) type(f_pthread_rwlock_t), intent(inout):: rwlock end function f_pthread_rwlock_wrlock |
f_pthread_rwlockattr_destroy
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. Return Codes: If this function completes successfully, value 0 is returned. Otherwise, the following error will be returned: EINVAL The argument rwattr is invalid. Example:
integer(4) function f_pthread_rwlockattr_destroy(rwattr) type(f_pthread_rwlockattr_t), intent(inout):: rwattr end function f_pthread_rwlockattr_destroy |
f_pthread_rwlockattr_getpshared
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 argumentpshared. pshared will contain one of the following values:
Return Codes: 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. Example:
integer(4) function f_pthread_rwlockattr_getpshared(rwattr, pshared) type(f_pthread_rwlockattr_t), intent(in):: rwattr integer(4), intent(out):: pshared end function f_pthread_rwlockattr_getpshared |
f_pthread_rwlockattr_init
This function initializes a read-write lock attributes object specified by rwattr with the default value for all of the attributes. Return Codes: If this function completes successfully, value 0 is returned. Otherwise, the following error will be returned: ENOMEM There is insufficient memory to initialize the read-write lock attributes object. Example:
integer(4) function f_pthread_rwlockattr_init(rwattr) type(f_pthread_rwlockattr_t), intent(out):: rwattr end function f_pthread_rwlockattr_init |
f_pthread_rwlockattr_setpshared
This function is used to set the process-shared attribute in an initialized read-write lock attributes object specified by the argument rwattr. The argument pshared must have one of the following values:
Return Codes: If this function completes successfully, value 0 is returned. Otherwise, one of the following errors will be returned: EINVAL The argument rwattr is invalid. EINVAL The new value specified for the attribute is invalid. Example:
integer(4) function f_pthread_rwlockattr_setpshared(rwattr, pshared) type(f_pthread_rwlockattr_t), intent(inout):: rwattr integer(4), intent(in):: pshared end function f_pthread_rwlockattr_setpshared |
f_pthread_rwlockattr_t
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. This data type corresponds to the AIX 4.3 data type pthread_rwlockattr_t, which is the type of the read-write lock attributes objects. |
f_pthread_self
This function can be used to return the thread ID of the calling thread. Example:
type(f_pthread_t) function f_pthread_self() end function Return Codes: The calling thread's ID is returned. |
f_pthread_setcancelstate
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. These arguments will assume the value of one of the following Fortran constants:
Return Codes: If errors are detected during the execution of this function, the following error code will be returned:
Example:
integer function f_pthread_setcancelstate(state, oldstate) integer(4), intent(in):: state integer(4), intent(out):: oldstate end function |
f_pthread_setcanceltype
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. These arguments will assume the value of one of the following Fortran constants:
Return Codes: If errors are detected during the execution of this function, the following error code will be returned:
Example:
integer function f_pthread_setcanceltype(type, oldtype) integer(4), intent(in):: type integer(4), intent(out):: oldtype end function |
f_pthread_setconcurrency
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. For more information about the concurrency level, refer to the AIX Operating System documentation. Return Codes: If this function completes successfully, value 0 is returned. Otherwise, one of the following errors will be returned: EINVAL The value specified by new_level is negative. EAGAIN The value specified by new_level would cause system resource to be exceeded. Example:
integer(4) function f_pthread_setconcurrency(new_level) integer(4), intent(in):: new_level end function f_pthread_setconcurrency |
f_pthread_setschedparam
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 valid scheduling policies on AIX can be found in the AIX Operating System documentation. 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. The new policy cannot be set to first-in first-out or round-robin unless the caller has root authority. For more details about when the new scheduling property has effect on the target thread, refer to the AIX Operating System documentation. Return Codes: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_setschedparam(thread, policy, param) type(f_pthread_t), intent(inout):: thread integer(4), intent(in):: policy type(f_sched_param), intent(in):: param end function |
f_pthread_setspecific
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. Currently, only an integer pointer can be passed as the arg argument. If arg is not an integer pointer, the result is undefined. RETURN CODES: If errors are detected during the execution of this function, one of the following error codes will be returned:
Example:
integer function f_pthread_setspecific(key, arg) type(f_pthread_key_t), intent(in):: key pointer(arg, byte) optional arg intent(in) arg end function |
f_pthread_t
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. |
f_pthread_testcancel
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. Example: subroutine f_pthread_testcancel() end subroutine |
f_sched_param
This data type corresponds to the AIX system data structure sched_param, which is a system data type. See AIX Operating System documentation for more information. Example: This is a public data structure defined as: type f_sched_param sequence integer sched_priority integer sched_policy integer reserved(6) end type f_sched_param |
f_sched_yield
This function is used to force the calling thread to relinquish the processor until it again becomes the head of its thread list. Return Codes: If this function completes successfully, value 0 is returned. Otherwise, a value of -1 will be returned. Example:
integer(4) function f_sched_yield() end function f_sched_yield |
f_timespec
This is a Fortran definition of the AIX 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. See AIX Operating System documentation for more information. Any 64-bit application that uses this data structure will use the symbolic constant time_size to specify the kind type parameter of the tv_sec intrinsic data type. TIME_SIZE is defined in the f_pthread module files. It is set either to '4' for 32-bit applications and 64-bit non-LDT applications, or to '8' for 64-bit LDT applications. Example: This is a public data structure defined as: type f_timespec sequence integer(kind=time_size) tv_sec integer tv_nsec end type f_timespec |