PH07475: STACK64 USAGE DOCUMENTATION UPDATE

APAR status

• Closed as documentation error.

Error description

• Problem description
  
  Book Title -  Language Environment Programming Guide for 64-bit
                Virtual Addressing Mode
  Book Number - SA380689xx
  Chapter  -  Stack and heap storage
  Section - Stack storage overview
  PMR Number - 00254,057,649
  Initials - CTW/NJL
  
  
  Explanation:
  ---
  The AMODE 64 LE stack settings will allocate a minimum of 1M
  for the initial and 1M for the increment - these will always be
  allocated.  Note, if zero is specified, values will always be
  rounded up to the nearest 1M (so zero still results in a 1M
  allocation).
  
     Refer to the STACK64 documentation in the z/OS Language
  Environment Programming Reference.  Note, the same applies if
  THREADSTACK64 is in use.
  
  The caveat to this, adding an additional 1M is the storage
  associated with managing the stack storage, also rounded up to
  the nearest 1M (generally 1M per thread).
  
  All combined, this means there is always a minimum allocation
  for AMODE64 stack storage of 3M per thread.
  
  
  When LE allocates the storage, we will set the guard areas
  respectively for user stack and reserve stack. Assuming we only
  need 1MB for the initial user stack, then the memory layout sort
  of like this:
  
            Low  +----------------+-------------
                 |    Guarded     |  nMB(guard)    |
                 |      Area      |             Maximum
   Stack Floor ->+----------------+              Stack
                 |    Initial     |             Segment
                 |      User      |  1MB(real)    Size
                 |     Stack      |                |
           BOS ->+----------------+-------------
                 |    Guarded     |  1MB(guard)
                 |      Area      |
                 +----------------+
                 |    Reserve     |  1MB(real)
                 |     Stack      |
                 +----------------+-------------
                 |      LE        |
                 |    Control     |  1MB(real)
                 |     Blocks     |
           High  +----------------+
  
     So at least 3MB are backed by real storage.
  ---
  
  
  
  
  
  Documentation change:
  
  Add the following information to this chapter:
  --
  MEMLIMIT for Large Number of Threads
  
  
  Every thread running AMODE64 requires a minimum of 3MB of
  above the bar virtual storage for each thread's stack storage.
  Specifying a maximum stack size of less than 1M will be rounded
  up and result in 3M of storage used.
  
  For example, a large application with 1000 threads, the MEMLIMIT
  would need to be increased by 3GB (1000 * 3MB) for thread stack
  virtual storage.
  --
  
  
  
  
  
  Keywords: HLE77B0 HLE77A0 CEL LE STACK64 THREADSTACK64 7A0 7B0
  MEMLIMIT
  

Local fix

• N/A
  

Problem summary

• ****************************************************************
  * USERS AFFECTED:  Language Environment users who run AMODE64  *
  *                  multi-threaded applications and experience  *
  *                  out of storage errors.                      *
  ****************************************************************
  * PROBLEM DESCRIPTION:  Every thread running AMODE64 requires  *
  *                       a minimum of 3MB of virtual storage    *
  *                       for each thread's stack storage. If    *
  *                       the MEMLIMIT is not large enough for   *
  *                       all the running threads, out of        *
  *                       storage error may occur.               *
  ****************************************************************
  * RECOMMENDATION:                                              *
  ****************************************************************
   See the problem description.
  

Problem conclusion

• z/OS XL C/C++ Programming Guide has been updated with adding a
   section to indicate that every thread running in AMODE64
   requires at least 3MB of virtual storage for its stack storage
   and control blocks.
  
   z/OS XL C/C++ Programming Guide >
   Coding: Advanced Topics >
   Using threads in z/OS UNIX applications >
   Behaviors and restrictions in z/OS UNIX applications >
  
   After section "Threads and recoverable resources", add the
   following section.
  
   MEMLIMIT for 64bit multi-threaded applications
   Every thread running in AMODE64 requires at least 3MB virtual
   storage above the bar for its stack storage and control blocks.
   For applications with large amount of threads, the MEMLIMIT
   would need to be set to a large enough value for thread stack
   virtual storage.
  

Temporary fix

Comments

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

Fix information

Applicable component levels