Memory Manager Configuration Settings

MX_MEMORY_SYSTEM_LIMIT sets the maximum amount of memory that may be used by the Studio Modeling Native Apps (all C++ threads). The default is 2g for the Studio Modeling Native Apps. For 3DSpace Services, this variable is set according to the Java heap size selected during installation. For 32-bit installations, the values are:
```
small = 450m
medium = 640m
large = 640m
```
For 64-bit installations, the values are:
```
small = 2048m
medium = 4096m
large = 6144m
```
The 3DSpace kernel is a native library (C++) and therefore allocates memory outside the java heap designation; that is the java heap of the java command line allocates memory for java and not for the 3DSpace kernel. MX_MEMORY_SYSTEM_LIMIT is meant to be the high water mark of allowable memory allocation for the native kernel. The 3DSpace memory manager tracks the number of bytes allocated and will issue warnings for every allocation over the MX_MEMORY_SYSTEM_LIMIT. There are several areas in the kernel that will also look for allocations over the MX_MEMORY_SYSTEM_LIMIT and abort the transaction. These checks are places in functional areas that are known to be memory intensive (database rowset loading, queries, expands and history lookups). The goal is to have the kernel abort the transaction that is consuming large amounts of memory while allowing the other threads to continue working.

To set this value appropriately, first determine the memory footprint for the process running the kernel. Depending on the OS, the total memory available to a process is between 1.7 and approximately 4g. Some operating systems require some configuration to achieve maximum memory footprint. Check vendor documentation for details. Adjust the total process size if the system doesn't have adequate free physical RAM or a smaller memory footprint is desired.

Once the desired memory footprint for a process is determined, the free, native and Java heap need to be sized appropriately. Divide the total memory available to the process into 3 groups: Free, Native and Java Heap:
- Native size is be governed by MX_MEMORY_SYSTEM_LIMIT.
- Java Heap is controlled by the java command line options Xmx -Xms.
- Free is simply a chunk of untouched memory that allows the kernel to allocate memory beyond the MX_MEMORY_SYSTEM_LIMIT. There isn't a configuration option that corresponds to Free. A conservative value for Free would be 100m.
To size the Java Heap and MX_MEMORY_SYSTEM_LIMIT appropriately, a profile of the app running under normal load is necessary.
Run java with the -verbose:gc option to show the pattern of GC (garbage collection) that occurs in the process. Full GC or frequent partial GCs indicates that the java heap is sized too small and the heap settings should be increased. Infrequent partial GC indicates that the heap is sized too large and memory is not being properly utilized. Sizing java heap too large can also affect performance, as garbage collection has more to rummage through.Once, the java heap is sized appropriately, run the kernel with the MX_MEMORY_TRACE option to log native memory allocation that occurs in the process. Every dispatch in to the kernel will report a high water mark for memory usage during that dispatch. This high water value is reset after each dispatch so memory allocation spikes can be tracked. Statistics on this high water mark (high, top 10, average) can be used to size MX_MEMORY_SYSTEM_LIMIT appropriately or determine whether the MX_MEMORY_SYSTEM_LIMIT is adequate. If the MX_MEMORY_SYSTEM_LIMIT is not adequate, consider increasing it if possible. Also, consider configurations that include clustering the 3DSpace kernel (multiple RIP instances front ended by a load balancer). Sorting of log files could be done with the following:
```
sort -n +12 memory.log | grep highwater
```
When setting the system memory limit, it is important to also consider the memory being used by the Java VM (as set on the Java command line via -Xmx -Xms). The sum of the Java settings and the MX_MEMORY_SYSTEM_LIMIT setting is the amount of memory that will actually be used and so must not exceed the amount available. Refer to Load Runner Example for ENOVIA lab test results.
MX_MEMORY_KEEP_LIMIT sets the threshold at which the manager begins freeing memory. The memory manager uses a "greedy" allocation algorithm; once memory has been allocated, the manager will try to reuse it rather than free it, until this threshold is met. The default value is 256m. Higher values will mean fewer operating system calls to allocate and free memory, and a larger process size while the server is running.
Note: Set MX_MEMORY_KEEP_LIMIT to 1 to prevent any memory retention at the Live Collaboration kernel level.
MX_MEMORY_TRACE enables minimal trace messages in the 3DSpace Service. These messages display a summary of memory blocks in use, and number of memory blocks reserved (see MX_MEMORY_KEEP_LIMIT). Use of this trace option will not substantially impact server performance.
Note: As with other MX_*_TRACE parameters, setting to TRUE will cause the output to go to stdout for the process in which the Live Collaboration kernel is running; specifying a filename will write the output to a file of the given name in the directory specified by MX_TRACE_FILE_PATH.
MX_MEMORY_THREAD_LIMIT sets the maximum amount of memory that may be used for a single 3DSpace thread. The default is 1g. Should allocation attempts be made beyond this size, warning messages will be written to the server log that identify the program file name and line number.
MX_MEMORY_PASSTHRU when set to TRUE, turns off the memory manager, which is on by default when either the Studio Modeling Native Apps or 3DSpace Service is installed. This setting may be used for diagnostic purposes if it is suspected the memory manager itself is causing a problem. Note this setting must be an environment variable; it CANNOT be placed in the .ini file, as it is (necessarily) interrogated before the system is initialized.
Note: When configuring all of the memory limits, the value field recognizes the same abbreviations used by the java vm: 'k' for kilobyte, 'm' for megabyte and 'g' for gigabyte.