================================================================================ 1/11 ================================================================================ < additions to the XBD 4.10 Memory Synchronization > The informal semantics of acquire/release memory synchronization operations can be defined(*) as: (1) before an ordinary load or store access is allowed to perform with respect to any other processor, all preceding acquire accesses must be performed, and (2) before a release access is allowed to perform with respect to any other processor, all preceding ordinary load and store accesses must be performed. An act of acquiring mutex ownership can be viewed as performing an acquire operation. An act of releasing mutex ownership can be viewed as performing a release operation. The pthread_refcount_decrement() and pthread_refcount_subtract() functions shall have the effect of /release/ memory synchronization operation if the resulting value of a reference count is not zero; otherwise, these functions shall have the effect of /acquire/ memory synchronization operation. The pthread_refcount_decrement_relmsync() and pthread_refcount_subtract_relmsync() functions shall have the effect of /release/ memory synchronization operation if the resulting value of a reference count is not zero; otherwise, the memory synchronization effect of these functions is unspecified. The pthread_refcount_decrement_acqmsync() and pthread_refcount_subtract_acqmsync() functions shall have the effect of /acquire/ memory synchronization operation if the resulting value of a reference count is zero; otherwise, the memory synchronization effect of these functions is unspecified. (*) http://rsim.cs.uiuc.edu/~sadve/Publications/thesis.ps ================================================================================ 2/11 ================================================================================ NAME pthread_refcountattr_destroy, pthread_refcountattr_init - destroy and initialize the reference count attributes object SYNOPSIS [THR RC] #include int pthread_refcountattr_destroy(pthread_refcountattr_t *attr); int pthread_refcountattr_init(pthread_refcountattr_t *attr); DESCRIPTION The pthread_refcountattr_destroy() function shall destroy a reference count attributes object; the object becomes, in effect, uninitialized. An implementation may cause pthread_refcountattr_destroy() to set the object specified by /attr/ to an invalid value. A destroyed /attr/ attributes object can be reinitialized using pthread_refcountattr_init(); the results of otherwise referencing the object after it has been destroyed are undefined. The pthread_refcountattr_init() function shall initialize a reference count attributes object /attr/ with the default value for all of the attributes defined by the implementation. Results are undefined if pthread_refcountattr_init() is called specifying an already initialized /attr/ attributes object. After a reference count attributes object has been used to initialize one or more reference counts, any function affecting the attributes object (including destruction) shall not affect any previously initialized reference counts. RETURN VALUE Upon successful completion, pthread_refcountattr_destroy() and pthread_refcountattr_init() shall return zero; otherwise, an error number shall be returned to indicate the error. ERRORS The pthread_refcountattr_destroy() function may fail if: [EINVAL] The object specified by /attr/ is invalid. The pthread_refcountattr_init() function shall fail if: [ENOMEM] Insufficient memory exists to initialize the reference count attributes object. These functions shall not return an error code of [EINTR]. -------------------------------------------------------------------------------- The following sections are informative. EXAMPLES None. APPLICATION USAGE None. RATIONALE . ================================================================================ 3/11 ================================================================================ NAME pthread_refcountattr_getpshared, pthread_refcountattr_setpshared - get and set the process-shared attribute SYNOPSIS [THR TSH RC] #include int pthread_refcountattr_getpshared(const pthread_refcountattr_t * restrict attr, int *restrict pshared); int pthread_refcountattr_setpshared(pthread_refcountattr_t *attr, int pshared); DESCRIPTION The pthread_refcountattr_getpshared() function shall obtain the value of the /process-shared/ attribute from the attributes object specified by /attr/. The pthread_refcountattr_setpshared() function shall set the /process-shared/ attribute in an initialized attributes object specified by /attr/. The /process-shared/ attribute is set to PTHREAD_PROCESS_SHARED to permit a reference count to be operated upon by any thread that has access to the memory where the reference count is allocated, even if the reference count is allocated in memory that is shared by multiple processes. If the /process-shared/ attribute is PTHREAD_PROCESS_PRIVATE, the reference count shall only be operated upon by threads created within the same process as the thread that initialized the reference count; if threads of different processes attempt to operate on such a reference count, the behavior is undefined. The default value of the attribute shall be PTHREAD_PROCESS_PRIVATE. The results are undefined if these functions are called with an uninitialized reference count attributes object. RETURN VALUE Upon successful completion, pthread_refcountattr_setpshared() shall return zero; otherwise, an error number shall be returned to indicate the error. Upon successful completion, pthread_refcountattr_getpshared() shall return zero and store the value of the /process-shared/ attribute of /attr/ into the object specified by the pshared parameter. Otherwise, an error number shall be returned to indicate the error. ERRORS The pthread_refcountattr_getpshared() and pthread_refcountattr_setpshared() functions may fail if: [EINVAL] The object specified by /attr/ is invalid. The pthread_refcountattr_setpshared() function may fail if: [EINVAL] The new value specified for the attribute is outside the range of legal values for that attribute. These functions shall not return an error code of [EINTR]. -------------------------------------------------------------------------------- The following sections are informative. EXAMPLES None. APPLICATION USAGE None. RATIONALE None. ================================================================================ 4/11 ================================================================================ NAME pthread_refcountattr_getprioceiling, pthread_refcountattr_setprioceiling - get and set the prioceiling attribute of the reference count attributes object (REALTIME THREADS) SYNOPSIS [THR TPP RC !RCNB] #include int pthread_refcountattr_getprioceiling(const pthread_refcountattr_t * restrict attr, int *restrict prioceiling); int pthread_refcountattr_setprioceiling(pthread_refcountattr_t *attr, int prioceiling); DESCRIPTION The pthread_refcountattr_getprioceiling() and pthread_refcountattr_setprioceiling() functions, respectively, shall get and set the priority ceiling attribute of a reference count attributes object specified by /attr/ which was previously created by the function pthread_refcountattr_init(). The prioceiling attribute contains the priority ceiling of initialized reference counts. The values of prioceiling are within the maximum range of priorities defined by SCHED_FIFO. The prioceiling attribute defines the priority ceiling of initialized reference counts, which is the minimum priority level at which the internal critical sections used by the reference count are executed. In order to avoid priority inversion, the priority ceiling of the reference count shall be set to a priority higher than or equal to the highest priority of all the threads that may operate on that reference count. The values of prioceiling are within the maximum range of priorities defined under the SCHED_FIFO scheduling policy. The results are undefined if these functions are called with an uninitialized reference count attributes object. RETURN VALUE Upon successful completion, the pthread_refcountattr_getprioceiling() and pthread_refcountattr_setprioceiling() functions shall return zero; otherwise, an error number shall be returned to indicate the error. ERRORS The pthread_refcountattr_getprioceiling() and pthread_refcountattr_setprioceiling() functions may fail if: [EINVAL] The object specified by /attr/ or /prioceiling/ is invalid. [EPERM] The caller does not have the privilege to perform the operation. These functions shall not return an error code of [EINTR]. -------------------------------------------------------------------------------- The following sections are informative. EXAMPLES None. APPLICATION USAGE None. RATIONALE None. ================================================================================ 5/11 ================================================================================ NAME pthread_refcountattr_getprotocol, pthread_refcountattr_setprotocol - get and set the protocol attribute of the reference count attributes object (REALTIME THREADS) SYNOPSIS [THR TPP|TPI RC !RCNB] #include int pthread_refcountattr_getprotocol(const pthread_refcountattr_t * restrict attr, int *restrict protocol); int pthread_refcountattr_setprotocol(pthread_refcountattr_t *attr, int protocol); DESCRIPTION The pthread_refcountattr_getprotocol() and pthread_refcountattr_setprotocol() functions, respectively, shall get and set the protocol attribute of a reference count attributes object specified by /attr/ which was previously created by the function pthread_refcountattr_init(). The /protocol/ attribute defines the protocol to be followed in utilizing reference counts. The value of protocol may be one of: PTHREAD_PRIO_NONE [TPI] PTHREAD_PRIO_INHERIT [TPP] PTHREAD_PRIO_PROTECT which are defined in the header. When a thread operates on a reference count with the PTHREAD_PRIO_NONE protocol attribute, its priority and scheduling shall not be affected. [TPI] When a thread is blocking higher priority threads because of operating on a reference count with the PTHREAD_PRIO_INHERIT protocol attribute, it shall execute at the higher of its priority or the priority of the highest priority thread waiting on a reference count and on any of the mutexes owned by this thread and initialized with this protocol. [TPP] When a thread owns one or more mutexes initialized with the PTHREAD_PRIO_PROTECT protocol or operates on a reference count initialized with the PTHREAD_PRIO_PROTECT protocol, it shall execute at the higher of its priority or the highest of the priority ceilings of all the mutexes owned and the reference count that is operated by this thread and initialized with this attribute, regardless of whether other threads are blocked on this reference count or not, and regardless of whether other threads are blocked on any of these mutexes or not. While a thread is operating on a reference count which has been initialized with the PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT protocol attributes, it shall not be subject to being moved to the tail of the scheduling queue at its priority in the event that its original priority is changed, such as by a call to sched_setparam(). Likewise, when a thread completes an operation on a reference count that has been initialized with the PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT protocol attributes, it shall not be subject to being moved to the tail of the scheduling queue at its priority in the event that its original priority is changed. [TPI] When a thread makes a call to pthread_refcount_getvalue(), pthread_refcount_increment(), pthread_refcount_increment_positive(), pthread_refcount_add(), pthread_refcount_add_to_positive(), pthread_refcount_decrement(), pthread_refcount_decrement_relmsync(), pthread_refcount_decrement_acqmsync(), pthread_refcount_decrement_nomsync(), pthread_refcount_subtract(), pthread_refcount_subtract_relmsync(), pthread_refcount_subtract_acqmsync(), pthread_refcount_subtract_nomsync(), the reference count was initialized with the protocol attribute having the value PTHREAD_PRIO_INHERIT, when the calling thread is blocked because the reference count is operated by another thread, that owner thread shall inherit the priority level of the calling thread as long as it continues to operate on the reference count. The implementation shall update its execution priority to the maximum of its assigned priority and all its inherited priorities. The results are undefined if these functions are called with an uninitialized reference count attributes object. RETURN VALUE Upon successful completion, the pthread_refcountattr_getprotocol() and pthread_refcountattr_setprotocol() functions shall return zero; otherwise, an error number shall be returned to indicate the error. ERRORS The pthread_refcountattr_setprotocol() function shall fail if: [ENOTSUP] The value specified by protocol is an unsupported value. The pthread_refcountattr_getprotocol() and pthread_refcountattr_setprotocol() functions may fail if: [EINVAL] The object specified by /attr/ or /protocol/ is invalid. [EPERM] The caller does not have the privilege to perform the operation. These functions shall not return an error code of [EINTR]. -------------------------------------------------------------------------------- The following sections are informative. EXAMPLES None. APPLICATION USAGE None. RATIONALE None. ================================================================================ 6/11 ================================================================================ NAME pthread_refcount_destroy, pthread_refcount_init - destroy and initialize a reference count SYNOPSIS [THR RC] #include int pthread_refcount_destroy(pthread_refcount_t *refcount); int pthread_refcount_init(pthread_refcount_t *restrict refcount, const pthread_refcountattr_t *restrict attr, size_t initial_value); pthread_refcount_t refcount = PTHREAD_REFCOUNT_INITIALIZER(N); DESCRIPTION The pthread_refcount_destroy() function shall destroy the reference count object specified by /refcount/; the reference count object becomes, in effect, uninitialized. An implementation may cause pthread_refcount_destroy() to set the object specified by /refcount/ to an invalid value. A destroyed reference count object can be reinitialized using pthread_refcount_init(); the results of otherwise referencing the object after it has been destroyed are undefined. The results are undefined if pthread_refcount_destroy() is called when any thread is operating on the reference count, or if this function is called with an uninitialized reference count. The pthread_refcount_init() function shall initialize the reference count specified by /refcount/ with attributes specified by /attr/. If /attr/ is NULL, the default reference count attributes are used; the effect shall be the same as passing the address of a default reference count attributes object. Upon successful initialization, the state of the reference count becomes initialized and its value shall be /initial_value/. Only /refcount/ itself may be used for performing reference counting. The result of referring to copies of /refcount/ in calls to pthread_refcount_getvalue(), pthread_refcount_setvalue(), pthread_refcount_increment(), pthread_refcount_add(), pthread_refcount_increment_positive(), pthread_refcount_add_to_positive(), pthread_refcount_decrement(), pthread_refcount_subtract(), pthread_refcount_decrement_nomsync(), pthread_refcount_subtract_nomsync(), pthread_refcount_decrement_relmsync(), pthread_refcount_subtract_relmsync(), pthread_refcount_decrement_acqmsync(), pthread_refcount_subtract_acqmsync(), and pthread_refcount_destroy() is undefined. Attempting to initialize an already initialized reference count results in undefined behavior. In cases where default reference count attributes are appropriate, the macro PTHREAD_REFCOUNT_INITIALIZER can be used to initialize reference counts that are statically allocated. The effect shall be equivalent to dynamic initialization by a call to pthread_refcount_init() with parameter /attr/ specified as NULL and with parameter /initial_value/ specified as N, except that no error checks are performed. RETURN VALUE If successful, the pthread_refcount_destroy() and pthread_refcount_init() functions shall return zero; otherwise, an error number shall be returned to indicate the error. The [EBUSY] and [EINVAL] error checks, if implemented, act as if they were performed immediately at the beginning of processing for the function and shall cause an error return prior to modifying the state of the reference count specified by /refcount/. ERRORS The pthread_refcount_destroy() function may fail if: [EBUSY] The implementation has detected an attempt to destroy the object specified by /refcount/ while it is in use by another thread. [EINVAL] The object specified by /refcount/ is invalid. The pthread_refcount_init() function shall fail if: [EAGAIN] The system lacked the necessary resources (other than memory) to initialize another reference count. [ENOMEM] Insufficient memory exists to initialize the reference count. [EPERM] The caller does not have the privilege to perform the operation. The pthread_refcount_init() function may fail if: [EBUSY] The implementation has detected an attempt to reinitialize the object specified by /refcount/, a previously initialized, but not yet destroyed, reference count. [EINVAL] The object specified by /attr/ is invalid. [EINVAL] The value specified by /initial_value/ is invalid. These functions shall not return an error code of [EINTR]. -------------------------------------------------------------------------------- The following sections are informative. EXAMPLES None. APPLICATION USAGE . RATIONALE ================================================================================ 7/11 ================================================================================ NAME pthread_refcount_getvalue, pthread_refcount_setvalue - get and set the value of a reference count SYNOPSIS [THR RC] #include int pthread_refcount_getvalue(pthread_refcount_t *refcount, size_t *restrict value_ptr); int pthread_refcount_setvalue(pthread_refcount_t *refcount, size_t value); DESCRIPTION The pthread_refcount_getvalue() function shall update the location specified by the /value_ptr/ argument to have the value of the reference count specified by /refcount/ without affecting the value of the reference count. The updated value represents an actual reference count value that occurred at some unspecified time during the call, but it need not be the actual value of the reference count when it is returned to the calling thread. The pthread_refcount_setvalue() function shall update the value of reference count specified by /refcount/ to become equal to /value/. The results are undefined if pthread_refcount_setvalue() is called while other thread is operating on the reference count. The results are undefined if these functions are called with an uninitialized reference count. RETURN VALUE If successful, the pthread_refcount_getvalue() and pthread_refcount_setvalue() functions shall return zero; otherwise, an error number shall be returned to indicate the error. ERRORS The pthread_refcount_getvalue() function may fail if: [EINVAL] The object specified by /refcount/ is invalid. The pthread_refcount_setvalue() function may fail if: [EINVAL] The object specified by /refcount/ is invalid. [EBUSY] The implementation has detected an attempt to update the value of the reference count specified by /refcount/ while other thread is operating on the reference count. These functions shall not return an error code of [EINTR]. -------------------------------------------------------------------------------- The following sections are informative. EXAMPLES None. APPLICATION USAGE . RATIONALE ================================================================================ 8/11 ================================================================================ NAME pthread_refcount_increment, pthread_refcount_increment_positive - increment the value of a reference count SYNOPSIS [THR RC] #include int pthread_refcount_increment(pthread_refcount_t *refcount); int pthread_refcount_increment_positive(pthread_refcount_t *refcount); DESCRIPTION The pthread_refcount_increment() function shall increment the value of the reference count specified by /refcount/ by adding 1 to it. The pthread_refcount_increment_positive() function shall increment the positive value of the reference count specified by /refcount/ by adding 1 to it. When value of the reference count is zero the pthread_refcount_increment_positive() function shall not increment the value of the reference count and the constant PTHREAD_REFCOUNT_DROPPED_TO_ZERO shall be returned to the calling thread. The constant PTHREAD_REFCOUNT_DROPPED_TO_ZERO is defined in and its value shall be distinct from any other value returned by pthread_refcount_increment_positive() function. The constant PTHREAD_REFCOUNT_MAX is defined in and its value shall represent the maximum value of a reference count. The results are undefined if these functions are called with a reference count which has value PTHREAD_REFCOUNT_MAX. The results are undefined if these functions are called with an uninitialized reference count. RETURN VALUE If successful, the pthread_refcount_increment() function shall return zero; otherwise, an error number shall be returned to indicate the error. If successful, the pthread_refcount_increment_positive() function shall return zero or PTHREAD_REFCOUNT_DROPPED_TO_ZERO if the value of the reference count is zero. Otherwise, an error number shall be returned to indicate the error. ERRORS The pthread_refcount_increment() and pthread_refcount_increment_positive() functions may fail if: [EINVAL] The object specified by /refcount/ is invalid. [ERANGE] The value of the referenced count specified by /refcount/ is PTHREAD_REFCOUNT_MAX. These functions shall not return an error code of [EINTR]. -------------------------------------------------------------------------------- The following sections are informative. EXAMPLES None. APPLICATION USAGE None. RATIONALE None. ================================================================================ 9/11 ================================================================================ NAME pthread_refcount_add, pthread_refcount_add_to_positive - increase the value of a reference count SYNOPSIS [THR RC] #include int pthread_refcount_add(pthread_refcount_t *refcount, size_t value); int pthread_refcount_add_to_positive(pthread_refcount_t *refcount, size_t value); DESCRIPTION The pthread_refcount_add() function shall add the /value/ argument to the value of the reference count specified by /refcount/. The pthread_refcount_add_to_positive() function shall add the /value/ argument to the positive value of the reference count specified by /refcount/. When value of the reference count is zero the pthread_refcount_add_to_positive() function shall not modify the value of the reference count and the constant PTHREAD_REFCOUNT_DROPPED_TO_ZERO shall be returned to the calling thread. The constant PTHREAD_REFCOUNT_DROPPED_TO_ZERO is defined in and its value shall be distinct from any other value returned by pthread_refcount_add_to_positive() function. The constant PTHREAD_REFCOUNT_MAX is defined in and its value shall represet the maximum value of a reference count. The results are undefined if these functions are called with an uninitialized reference count. RETURN VALUE If successful, the pthread_refcount_add() function shall return zero; otherwise, an error number shall be returned to indicate the error. If successful, the pthread_refcount_add_to_positive() function shall return zero or PTHREAD_REFCOUNT_DROPPED_TO_ZERO if the value of the reference count is zero. Otherwise, an error number shall be returned to indicate the error. The [ERANGE] error check acts as if it was performed immediately at the beginning of processing for these functions and shall cause an error return prior to modifying the value of the reference count specified by /refcount/. ERRORS The pthread_refcount_add() and pthread_refcount_add_to_positive() functions shall fail if: [ERANGE] The sum of the values specified by /refcount/ and /value/ is greater than PTHREAD_REFCOUNT_MAX. The pthread_refcount_add() and pthread_refcount_add_to_positive() functions may fail if: [EINVAL] The object specified by /refcount/ is invalid. These functions shall not return an error code of [EINTR]. -------------------------------------------------------------------------------- The following sections are informative. EXAMPLES None. APPLICATION USAGE None. RATIONALE None. ================================================================================ 10/11 ================================================================================ NAME pthread_refcount_decrement, pthread_refcount_decrement_relmsync, pthread_refcount_decrement_acqmsync, pthread_refcount_decrement_nomsync - decrement the value of a reference count SYNOPSIS [THR RC] #include int pthread_refcount_decrement(pthread_refcount_t *refcount); int pthread_refcount_decrement_relmsync(pthread_refcount_t *refcount); int pthread_refcount_decrement_acqmsync(pthread_refcount_t *refcount); int pthread_refcount_decrement_nomsync(pthread_refcount_t *refcount); DESCRIPTION These functions shall decrement the value of the reference count specified by /refcount/. That is, the value 1 is subtracted from the value of the reference count specified by /refcount/. When the decremented value of the reference count is zero, the constant PTHREAD_REFCOUNT_DROPPED_TO_ZERO shall be returned to the calling thread. The constant PTHREAD_REFCOUNT_DROPPED_TO_ZERO is defined in and its value shall be distinct from any other value returned by these functions. The results are undefined if these functions are called with a reference count which has value zero. The results are undefined if these functions are called with an uninitialized reference count. RETURN VALUE If successful, these functions shall return zero or PTHREAD_REFCOUNT_DROPPED_TO_ZERO if the decremented value of the reference count is zero. Otherwise, an error number shall be returned to indicate the error. ERRORS The pthread_refcount_decrement(), pthread_refcount_decrement_relmsync(), pthread_refcount_decrement_acqmsync() and pthread_refcount_decrement_nomsync() functions may fail if: [EINVAL] The object specified by /refcount/ is invalid. [ERANGE] The value of the referenced count specified by /refcount/ is zero. These functions shall not return an error code of [EINTR]. -------------------------------------------------------------------------------- The following sections are informative. EXAMPLES None. APPLICATION USAGE None. RATIONALE None. ================================================================================ 11/11 ================================================================================ NAME pthread_refcount_subtract, pthread_refcount_subtract_relmsync, pthread_refcount_subtract_acqmsync, pthread_refcount_subtract_nomsync - decrease the value of a reference count SYNOPSIS [THR RC] #include int pthread_refcount_subtract(pthread_refcount_t *refcount, size_t value); int pthread_refcount_subtract_relmsync(pthread_refcount_t *refcount, size_t value); int pthread_refcount_subtract_acqmsync(pthread_refcount_t *refcount, size_t value); int pthread_refcount_subtract_nomsync(pthread_refcount_t *refcount, size_t value); DESCRIPTION These functions shall subtract the /value/ argument from the value of the referenced count specified by /refcount/. When the resulting value of the reference count is zero, the constant PTHREAD_REFCOUNT_DROPPED_TO_ZERO shall be returned to the calling thread. The constant PTHREAD_REFCOUNT_DROPPED_TO_ZERO is defined in and its value shall be distinct from any other value returned by these functions. The results are undefined if these functions are called with an uninitialized reference count. RETURN VALUE If successful, these functions shall return zero or PTHREAD_REFCOUNT_DROPPED_TO_ZERO if the resulting value of the reference count is zero. Otherwise, an error number shall be returned to indicate the error. The [ERANGE] error check acts as if it was performed immediately at the beginning of processing for these functions and shall cause an error return prior to modifying the value of the reference count specified by /refcount/. ERRORS The pthread_refcount_subtract, pthread_refcount_subtract_relmsync, pthread_refcount_subtract_acqmsync, pthread_refcount_subtract_nomsync functions shall fail if: [ERANGE] The value of the reference count specified by /refcount/ is less than /value/. The pthread_refcount_subtract, pthread_refcount_subtract_relmsync, pthread_refcount_subtract_acqmsync, pthread_refcount_subtract_nomsync functions may fail if: [EINVAL] The object specified by /refcount/ is invalid. These functions shall not return an error code of [EINTR]. -------------------------------------------------------------------------------- The following sections are informative. EXAMPLES None. APPLICATION USAGE None. RATIONALE None. ================================================================================ END ================================================================================