RWThreadAttribute

Module:  Threads   Package:  Threading

RWThreadAttribute   RWHandleBase

• Local Index
• Header File
• Description
• Example
• Global Enumerations
• Global Typedefs
• Feature Test Macros
• Public Constructors
• Public Destructor
• Public Member Functions
• Public Member Functions (by group)
• Public Member Operator
• canGet Functions
• canSet Functions
• get Functions
• getMax getMin Functions
• isXxxSet Functions
• reset Functions
• set Functions
• See Also

Members

canGetConcurrencyPolicy() canGetContentionScope() canGetInheritancePolicy() canGetPriority() canGetProcessScopePriority() canGetSchedulingPolicy() canGetStackCommitSize() canGetStackGuardSize() canGetStackReserveSize() canGetStartPolicy() canGetSystemScopePriority() canGetTimeSliceQuantum() canGetUserStack() canSetConcurrencyPolicy() canSetContentionScope() canSetInheritancePolicy() canSetPriority() canSetProcessScopePriority() canSetSchedulingPolicy() canSetStackCommitSize() canSetStackGuardSize() canSetStackReserveSize() canSetStartPolicy() canSetSystemScopePriority() canSetTimeSliceQuantum() canSetUserStack() copy()

getConcurrencyPolicy() getContentionScope() getInheritancePolicy() getMaxPriority() getMaxProcessScopePriority() getMaxSystemScopePriority() getMaxTimeSliceQuantum() getMinPriority() getMinProcessScopePriority() getMinStackSize() getMinSystemScopePriority() getMinTimeSliceQuantum() getPriority() getProcessScopePriority() getSchedulingPolicy() getStackCommitSize() getStackGuardSize() getStackReserveSize() getStartPolicy() getSystemScopePriority() getTimeSliceQuantum() getUserStackAddress() getUserStackSize() isConcurrencyPolicySet() isContentionScopeSet() isEqual() isInheritancePolicySet()

isPrioritySet() isProcessScopePrioritySet() isSchedulingPolicySet() isStackCommitSizeSet() isStackGuardSizeSet() isStackReserveSizeSet() isStartPolicySet() isSystemScopePrioritySet() isTimeSliceQuantumSet() isUserStackSet() operator=() resetConcurrencyPolicy() resetContentionScope() resetInheritancePolicy() resetPriority() resetProcessScopePriority() resetSchedulingPolicy() resetStackCommitSize() resetStackGuardSize() resetStackReserveSize() resetStartPolicy() resetSystemScopePriority() resetTimeSliceQuantum() resetUserStack() RWThreadAttribute() RW_THR_HAS_CONCURRENCY_POLICY RW_THR_HAS_CONTENTION_SCOPE

RW_THR_HAS_DUAL_PRIORITY RW_THR_HAS_INHERITANCE_POLICY RW_THR_HAS_PARTIAL_STACK_COMMITMENT RW_THR_HAS_PRIORITY RW_THR_HAS_PROCESS_SCOPE_PRIORITY RW_THR_HAS_SCHEDULING_POLICY RW_THR_HAS_STACK_COMMIT_SIZE RW_THR_HAS_STACK_GUARD_SIZE RW_THR_HAS_STACK_RESERVE_SIZE RW_THR_HAS_START_POLICY RW_THR_HAS_SYSTEM_SCOPE_PRIORITY RW_THR_HAS_TIME_SLICE_QUANTUM RW_THR_HAS_USER_STACK setConcurrencyPolicy() setContentionScope() setInheritancePolicy() setPriority() setProcessScopePriority() setSchedulingPolicy() setStackCommitSize() setStackGuardSize() setStackReserveSize() setStartPolicy() setSystemScopePriority() setTimeSliceQuantum() setUserStack() ~RWThreadAttribute()

Non-Members

RWConcurrencyPolicy RWContentionScope

RWInheritancePolicy RWPriority

RWSchedulingPolicy RWStartPolicy

#include <rw/thread/RWThreadAttribute.h> 

Class RWThreadAttribute encapsulates a set of attributes that define or control thread scheduling and stack allocation. By supplying an instance of this class to a thread object such as an RWThread you can configure the behavior of each new thread that you create. You can also use an RWThreadAttribute to retrieve the default values for the current environment and query the current environment as to which attributes may be legally retrieved and set under the current circumstances. This class also provides functions for querying the minimum and maximum allowable values for the various attributes. Please see the Threads Module User's Guide and the Threads Module Platform User's Guide for a complete discussion of thread attributes.

#include <rw/thread/RWThreadAttribute.h>     // for RWThreadAttribute
#include <rw/thread/RWRunnableSelf.h>        // for rwThread()
#include <rw/thread/rwtMakeThreadFunction.h> // for rwtMakeThreadFunction()

void checkContentionScope(void)
{
  RWThreadSelf me = rwThread();
  // Was this thread created by a Threading package class?
  if (me.isValid()) {

    // Get the attribute instance used to create the thread
    RWThreadAttribute attr = me.getActiveAttribute();

    // Is the contention scope attribute available?
    if (attr.canGetContentionScope()) {
      // Yes, then get the scope used to create the thread
      RWContentionScope cscope = attr.getContentionScope();

      switch (cscope) {
        case RW_THR_PROCESS_SCOPE:
          cout << "Process Scope" << endl;
          break;
        case RW_THR_SYSTEM_SCOPE:
          cout << "System Scope" << endl;
          break;
        default:
          cout << "Unexpected value for contention scope" 
               << endl;
      }
    }
    else
       cout << "Contention scope is not supported" << endl;
  }
}

int main()
{
  RWThread t1 = rwtMakeThreadFunction(checkContentionScope);
  cout << "Default: " << flush;
  t1.start();
  t1.join();

  RWThreadAttribute attr;
  // Is the desired contention scope policy supported?
  if (attr.canSetContentionScope(RW_THR_SYSTEM_SCOPE))
    attr.setContentionScope(RW_THR_SYSTEM_SCOPE);
  else
    cout << "Unable to set contention scope to \"System\""
         << endl;
  t1.setAttribute(attr);
  cout << "Set: " << flush;
  t1.start();
  t1.join();

  attr.resetContentionScope();
  t1.setAttribute(attr);
  cout << "Reset: " << flush;
  t1.start();
  t1.join();

  return 0;
}
/*
 * OUTPUT (Solaris):
 *
   Default: Process Scope
   Set: System Scope
   Reset: Process Scope
 *
 */

enum RWConcurrencyPolicy 

For a description of this global enumerator, which is defined in RWThreadAttribute.h, see the reference entry for RWConcurrencyPolicy.

enum RWContentionScope 

For a description of this global enumerator, which is defined in RWThreadAttribute.h, see the reference entry for RWContentionScope.

enum RWInheritancePolicy 

For a description of this global enumerator, which is defined in RWThreadAttribute.h, see the reference entry for RWInheritancePolicy.

enum RWSchedulingPolicy {

For a description of this global enumerator, which is defined in RWThreadAttribute.h, see the reference entry for RWSchedulingPolicy.

enum RWStartPolicy {

For a description of this global enumerator, which is defined in RWThreadAttribute.h, see the reference entry for RWStartPolicy.

typedef int   RWPriority;     // POSIX, Win32
typedef pri_t RWPriority;     // SOLARIS

RW_THR_HAS_CONCURRENCY_POLICY
RW_THR_HAS_CONTENTION_SCOPE
RW_THR_HAS_INHERITANCE_POLICY
RW_THR_HAS_PRIORITY
RW_THR_HAS_PROCESS_SCOPE_PRIORITY
RW_THR_HAS_SCHEDULING_POLICY
RW_THR_HAS_STACK_COMMIT_SIZE
RW_THR_HAS_STACK_GUARD_SIZE
RW_THR_HAS_STACK_RESERVE_SIZE
RW_THR_HAS_START_POLICY
RW_THR_HAS_SYSTEM_SCOPE_PRIORITY
RW_THR_HAS_TIME_SLICE_QUANTUM
RW_THR_HAS_USER_STACK

These macros, defined in rw/thr/defs.h, are used to indicate whether the corresponding attribute is supported in the current environment. If the macro is not defined, attempts to get or set the corresponding attribute will produce exceptions. If the macro is defined, the current environment has some level of support for the attribute, and may allow you to get or set the attribute value.

RW_THR_HAS_DUAL_PRIORITY

This macro indicates that the underlying system requires two priorities for threads with system contention scope -- one priority value for use in resolving system-level scheduling conflicts, and a second priority value for use in resolving contention for synchronization resources that are shared between threads within a process.

RW_THR_HAS_PARTIAL_STACK_COMMITMENT

This macro indicates that the underlying system allows partial stack commitment, meaning the stack commit size may be set to a value less that the stack reserve size. If this macro is not defined, then the stack reserve size and stack commit size attributes are mutually exclusive and only one or the other may be set.

RWThreadAttribute();

Default constructor.

RWThreadAttribute(RWStaticCtor);

Constructs a global static instance. The object will be initialized upon first use, and if the object is used before this constructor is called, any set values will not be overridden.

RWThreadAttribute(const RWThreadAttribute& second)

Copy constructor.

~RWThreadAttribute();

Destructor.

void
copy(const RWThreadAttribute& second);

Copies the thread attribute values from second.

bool
isEqual(const RWThreadAttribute& second) const;

Tests the equality of self against second on a value by value basis. Possible exceptions include RWTHRInternalError.

The bulk of the public member functions for this class are divided into 6 groups:

The "canGet" functions determine whether an attribute value can be read.

The "canSet" functions determine whether an attribute value can be set.

The "get" functions return an attribute value.

The "isXxxSet" functions determine whether an attribute has maintained its previously set value.

The "reset" functions restore an attribute to its default setting.

The "set" functions set an attribute value.

RWThreadAttribute&
operator=(const RWThreadAttribute& second);

Assignment operator.

bool
canGetConcurrencyPolicy() const;

bool
canGetContentionScope() const;

bool
canGetInheritancePolicy() const;

bool
canGetPriority() const;

bool
canGetProcessScopePriority() const;

bool
canGetSchedulingPolicy() const;

bool
canGetStackCommitSize() const;

bool
canGetStackGuardSize() const;

bool
canGetStackReserveSize() const;

bool
canGetStartPolicy() const;

bool
canGetSystemScopePriority() const;

bool
canGetTimeSliceQuantum() const;

bool
canGetUserStack() const;

These "canGet" test functions determine at runtime whether the corresponding attribute value may be read. Each of these functions returns false if the corresponding attribute is not supported in the current environment, or if the corresponding "get" function cannot return a legal value under current circumstances.

If the corresponding attribute value has not yet been "set", then a return value of true indicates that a default value is available and may be read.

These functions always return true if the corresponding attribute still has the value previously defined by a call to the matching "set" function. In this case the behavior is similar to that provided by the "isSet" functions, below. Possible exceptions include RWTHRInternalError.

bool
canSetConcurrencyPolicy(RWConcurrencyPolicy policy) const;

bool
canSetContentionScope(RWContentionScope scope) const;

bool
canSetInheritancePolicy(RWInheritancePolicy policy) const;

bool
canSetPriority() const;

bool
canSetProcessScopePriority() const;

bool
canSetSchedulingPolicy(RWSchedulingPolicy policy) const;

bool
canSetStackCommitSize() const;

bool
canSetStackGuardSize() const;

bool
canSetStackReserveSize() const;

bool
canSetStartPolicy(RWStartPolicy policy) const;

bool
canSetSystemScopePriority() const;

bool
canSetTimeSliceQuantum() const;

bool
canSetUserStack() const;

The "canSet" test functions determine, at runtime, whether the corresponding attribute value may be set. Each of these functions returns false if the corresponding attribute is not supported in the current environment or if the specified policy, if any, is not supported under the current circumstances. Otherwise, the function returns true. All of these functions can throw an RWTHRInternalError exception. In addition, those that take an argument can throw RWTHRBoundsError.

RWConcurrencyPolicy
getConcurrencyPolicy() const;

RWContentionScope 
getContentionScope() const;

RWInheritancePolicy
getInheritancePolicy() const;

RWPriority
getPriority() const;

RWPriority
getProcessScopePriority() const;

RWSchedulingPolicy
getSchedulingPolicy() const;

size_t
getStackCommitSize() const;

size_t
getStackGuardSize() const;

size_t
getStackReserveSize() const;

RWStartPolicy
getStartPolicy() const;

RWPriority
getSystemScopePriority() const;

unsigned long
getTimeSliceQuantum() const;

void*
getUserStackAddress() const;

size_t
getUserStackSize() const;

Use these functions to query the default value of an attribute, if available, or the last value defined in a call to the matching "set" function.

These functions will throw an RWTHROperationNotSupported exception if the attribute is not supported in the current environment. They will throw the RWTHROperationNotAvailable exception if the corresponding attribute is supported but has not yet been defined by a call to the matching "set" function, and no default value is available under the current circumstances. Other possible exceptions include RWTHRInternalError.

RWPriority
getMaxPriority() const;

RWPriority
getMaxProcessScopePriority() const;

RWPriority
getMaxSystemScopePriority() const;

unsigned long
getMaxTimeSliceQuantum() const;

RWPriority
getMinPriority() const;

RWPriority
getMinProcessScopePriority() const;

static
size_t
getMinStackSize();

RWPriority
getMinSystemScopePriority() const;

unsigned long
getMinTimeSliceQuantum() const;

Use these functions to determine the legal range of values for the various attributes. All of these functions can throw exceptions RWTHROperationNotSupported and RWTHRInternalError. In addition, all of these functions except getMinStackSize() can throw an RWTHROperationNotAvailable exception.

bool
isConcurrencyPolicySet() const;

bool
isContentionScopeSet() const;

bool
isInheritancePolicySet() const;

bool
isPrioritySet() const;

bool
isProcessScopePrioritySet() const;

bool
isSchedulingPolicySet() const;

bool
isStackCommitSizeSet() const;

bool
isStackGuardSizeSet() const;

bool
isStackReserveSizeSet() const;

bool
isStartPolicySet() const;

bool
isSystemScopePrioritySet() const;

bool
isTimeSliceQuantumSet() const;

bool
isUserStackSet() const;

The "isXxxSet" test functions determine whether the corresponding attribute still has the value specified in an earlier call to the matching "set" function.

Each of these functions returns false if the corresponding attribute is not supported in the current environment, has not yet been set, or has been forced to some other default value in response to a change in another related attribute. Otherwise true is returned. Possible exceptions include RWTHRInternalError.

void
resetConcurrencyPolicy();

void
resetContentionScope();

void
resetInheritancePolicy();

void
resetPriority();

void
resetProcessScopePriority();

void
resetSchedulingPolicy();

void
resetStackCommitSize();

void
resetStackGuardSize();

void
resetStackReserveSize();

void
resetStartPolicy();

void
resetSystemScopePriority();

void
resetTimeSliceQuantum();

void
resetUserStack();

These functions will restore an attribute value to its default setting, if any. These functions will always succeed, even if the target attribute is not supported in the current environment. There are several combinations of attributes and environments where it is not possible to query for a default value of an attribute. In those cases, the functions will simply clear any previous setting so that the Threads Module will know to rely on the underlying API to determine the appropriate default value. Possible exceptions include RWTHRInternalError and RWTHROperationNotSupported.

void
setConcurrencyPolicy(RWConcurrencyPolicy policy);

void
setContentionScope(RWContentionScope scope);

void
setInheritancePolicy(RWInheritancePolicy policy);

void
setPriority(RWPriority priority);

void
setProcessScopePriority(RWPriority priority);

void
setSchedulingPolicy(RWSchedulingPolicy policy);

void
setStackCommitSize(size_t size);

void
setStackGuardSize(size_t size);

void
setStackReserveSize(size_t size);

void
setStartPolicy(RWStartPolicy policy);

void
setSystemScopePriority(RWPriority priority);

void
setTimeSliceQuantum(unsigned long milliseconds);

void
setUserStack(void* address, size_t size);

Use these functions to set the corresponding attribute. The functions will throw the RWTHROperationNotSupported exception if the attribute is not supported in the current environment. They will throw the RWTHROperationNotAvaiable exception if the corresponding attribute is supported but the specified value is not supported under the current circumstances. Possible exceptions include RWTHRBoundsError, RWTHROperationNotAvailable, RWTHROperationNotSupported, and RWTHRInternalError.

RWThread, RWThreadSelf

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.