System-Managed Stack Attributes
The default choice for stack management policy is to let the system allocate and manage the stack, but the final choice between system-managed and user-managed stack allocation is determined by which attributes were most recently set. If the user-stack attributes were the last stack attributes changed prior to thread creation, then user-management of the stack is assumed.
The following attributes control system-managed stack allocation:
Stack Reserve Size—The stack reserve size attribute defines the amount of virtual address space to reserve for the stack.On most systems, reserving space for the stack only involves reserving virtual memory locations—memory and pagefile resources are not allocated until the memory is committed. No harm is caused by reserving a large area if it might be needed.
The feature test macro for stack reserve size is RW_THR_HAS_STACK_RESERVE_SIZE. If this macro is not defined, attempts to query or set the reserve size attribute always produce an exception. If it is defined, then the current environment has some level of support or recognition for stack reserve size and might allow you to get or set this attribute.
Stack reserve size is defined in terms of some number of bytes using size_t values. The actual sizes can be rounded to some environment-specific granularity (such as page size).
The RWThreadAttribute member functions that manipulate the stack reserve size include:
canGetStackReserveSize() — Indicates whether the stack reserve size is supported in the current environment and whether getStackReserveSize() can currently return a legal value.isStackReserveSizeSet() — Indicates whether the reserve size value is the value that was previously set by a call to setStackReserveSize(size_t).getStackReserveSize() — Returns the default reserve size value if the attribute value has not yet been defined. Otherwise, it returns the value specified in the last call to setStackReserveSize(size_t). If the current environment or circumstances do not allow interrogation of the stack reserve size, then attempts to use this function result in exceptions.canSetStackReserveSize() — Indicates whether the stack reserve size attribute is supported and can be set in the current environment.setStackReserveSize(size_t) — Sets the reserve size attribute to the value passed as an argument. If the current environment does not support this attribute or if the specified attribute value is outside the legal range, then the function produces an exception.resetStackReserveSize() — Restores the reserve size attribute to its default value. The default value and its source vary by environment.getMinStackSize() — Returns the minimum amount of stack space required to implement a thread that calls a null routine. The Threading package also ensures that a system-managed stack is of sufficient size by adding this value to any value defined using setStackReserveSize(size_t).If the current environment or circumstances do not allow interrogation of the minimum stack size, then attempts to use this function result in exceptions. The availability of this function can be inferred by testing the result returned by either canGetStackReserveSize() or canGetUserStack().
An attempt to read the default value for this attribute produces an exception if the user stack attributes have been set, unless the stack reserve or commit size is set or the user stack attributes are reset. In those cases, the default value of system-managed stack attributes are again available.
Systems vary in several ways:
You might not be allowed to change the amount of space reserved for a stack—sometimes the size is fixed at link time. When inheritance defines a thread’s stack reserve size, a method for determining this value might not be available. You might be allowed to choose the stack reserve size independently of stack commit size, which allows partial commitment to memory, or you might be allowed to specify only one or the other attribute (the stack is either reserved and can only be committed on demand, or the stack must be entirely committed, if at all).The specific attribute availability and validation criteria are unique to each environment and are documented in the appropriate chapters in the Threads Module Platform Guide.Stack Commit Size—The stack commit size attribute specifies the amount of physical memory and pagefile space to initially commit to the stack.The feature test macro for stack commit size is RW_THR_HAS_STACK_COMMIT_SIZE. If this macro is not defined, attempts to query or set the commit size attribute always produce an exception. If it is defined, then the current environment has some level of support or recognition for stack commit size and allows you to get or set this attribute.
Stack commit size is defined in terms of some number of bytes using size_t values. The actual sizes can be rounded to some environment-specific granularity (such as page size).
The RWThreadAttribute member functions that manipulate the stack commit size include:
canGetStackCommitSize() — Indicates whether the stack commit size is supported in the current environment and whether getStackCommitSize() can currently return a legal value.isStackCommitSizeSet() — Indicates whether the commit size value is the value that was previously set by a call to setStackCommitSize(size_t).getStackCommitSize() — Returns the default commit size value if the attribute value has not yet been defined. Otherwise, it returns the value specified in the last call to setStackCommitSize(size_t). If the current environment or circumstances do not allow interrogation of the time-slice quantum, then attempts to use this function result in exceptions.canSetStackCommitSize() — Indicates whether the stack commit size attribute is supported and can be set in the current environment.setStackCommitSize(size_t) — Sets the commit size attribute to the value passed as an argument. If the current environment does not support this attribute or if the specified attribute value is outside the legal range, then the function produces an exception.resetStackCommitSize() — Restores the commit size attribute to its default value. The default value and its source vary by environment.An attempt to read the default value for this attribute produces an exception if the user stack attributes have been set, unless the stack reserve or commit size is set or the user stack attributes are reset. In those cases, the default value of system-managed stack attributes are again available.
Systems vary in several ways:
You might not be allowed to specify the amount of memory to commit to the stack. When inheritance defines a thread’s stack reserve size, a method for determining this value might not be available. The specific attribute availability and validation criteria are unique to each environment and are documented in the appropriate section of the Threads Module Platform Guide.The macro RW_THR_HAS_PARTIAL_STACK_COMMITMENT indicates whether the current environment allows the user to specify that some amount of the memory space allocated for thread stack is to be committed to physical memory at creation.
If RW_THR_HAS_PARTIAL_STACK_COMMITMENT is defined, then the macro RW_THR_HAS_STACK_COMMIT_SIZE is defined. If RW_THR_HAS_STACK_COMMIT_SIZE is defined, but RW_THR_HAS_PARTIAL_STACK_COMMITMENT is not, then the commit size also specifies the amount of memory to reserve for the stack.
