kernelopts - Maple Programming Help

Online Help

All Products    Maple    MapleSim


Home : Support : Online Help : Programming : Resource Management : kernelopts

kernelopts

set or query kernel variables and options

 

Calling Sequence

Parameters

Description

Thread Safety

Examples

Compatibility

Calling Sequence

kernelopts(arg1, arg2, ... )

Parameters

arg1, arg2, ...

-

argument(s) of the form name=val or name

Description

• 

The kernelopts command is a mechanism for communication between the user and the Maple kernel. Specifically, this command is used to set and query variables that affect the computation of Maple. The variables that can be set and queried are as follows.

ASSERT

assertlevel

bindir

byteorder

bytesalloc

bytesused

cacheclearlimit

cpulimit

cputime

cputype

dagtag

datadir

datalimit

dirsep

display_zero_complex_part

filelimit

floatPi

gcbytesavail

gcbytesreturned

gcmaxthreads

gcthreadmemorysize

gctimes

gctotaltime

gmpthreshold

gmpversion

heaps

homedir

includepath

inline

jvmheaplimit

keepdebuginfo

level

limitjvmheap

locale

mapledir

max_record_depth

maxdigits

maximmediate

memusage

multithreaded

numcpus

numactivethreads

opaquemodules

pathsep

pid

platform

printbytes

'printlevel'

processlimit

profile

readdotm

setsort

shortlineinfo

sparse_sort_cutoff

stackalloc

stacklimit

system

toolboxdir

toolboxversion

traceincidentalassign

tracecatch

tracelineinfo

traceshowspecassign

tracesplitmulassign

unread

username

version

versionnumber

wordsize

• 

There is a Maplet interface to the kernelopts routine. For more information, see the Maplets[Examples][KernelOpts] help page.

• 

If an argument is of the form name=val then this specifies the setting for the named variable.

  

For each argument of this type, kernelopts returns the old value of the argument. This is convenient when you want to change and later restore a value, for example,

  

 

oldNumCPUs := kernelopts(numcpus=4);  # set new value and save old

. . . .

kernelopts(numcpus=oldNumCPUs);          # restore previous value

• 

If an argument is a name then the current value of the named variable is retrieved and returned as the function value.

• 

When kernelopts is called with many arguments, it returns an expression sequence containing the values.

• 

The cpulimit, datalimit, and stacklimit limit variables must be used carefully. When a limit is reached Maple may shutdown without warning. The option to save may not be given. On some platforms, including all Windows platforms, the detection of limit violations is tied to garbage collection. Therefore, the detection of limit violations is inaccurate for code that rarely invokes garbage collection. If garbage collection is never invoked, Maple does not detect limit violations.

• 

The filelimit and processlimit limit variables must also be used carefully. They limit the total number of files or processes that Maple can use. Some internal Maple functions open files or run processes and thus will fail if these limits are too low.

• 

The values assigned to the following kernelopts options can be modified by attaching a unit: cacheclearlimit, cpulimit, datalimit, jvmheaplimit, and stacklimit. When the conversion from the given unit to the default unit is not exact the value is rounded down. The units used for these options follow the IEC prefixes and definitions, with the exception of the unit word. For kernelopts a word is the wordsize of the current machine (either 32 or 64 bits). The return value for these options is the previous value in the default unit.

• 

Some kernelopts are most useful in the multithreaded Maple engine.  In particular the numcpus and numactivethreads have limited usefulness in the single threaded kernel.

• 

The standard set of kernelopts variables is:

NAME

VALUES

EXPLANATION

ASSERT

boolean

If true, ASSERT functions are evaluated as expected. If false (default), ASSERT functions are ignored. ASSERT is obsolete (but still supported) and has been replaced by assertlevel.

assertlevel

0, 1, 2

0 - assertions are not checked

 

 

1 -  only calls to the ASSERT function are checked

 

 

2 - calls to the ASSERT function, as well as assignment type assertions are checked.

 

 

The default value is 0.

bindir

string

The path to the system binary directory of the Maple installation. This value cannot be set.

byteorder

string

Either "little endian" or "big endian". This value cannot be set.

bytesalloc

integer

Total number of bytes allocated by the Maple mathematical kernel. This value cannot be set.

bytesused

integer

Total number of bytes used by the Maple mathematical kernel. This value cannot be set.

cacheclearlimit

integer

The data limit, in kibibytes, for maintaining temporary elements in cache tables. A check is performed whenever memory is allocated from the system. If the total amount of memory allocated exceeds this limit, cache tables will be automatically cleared of all temporary elements on the next garbage collection. Values passed for this option can be given with a Unit of information.

cpulimit

integer

The total amount of CPU time, in seconds that Maple may consume. Maple aborts if this time limit is exceeded. If the value is 0 or it is not given the current limit is returned. Limits may be raised or lowered. Maple limits cannot be raised above any system imposed hard limits. Values passed for this option can be given with a Unit of time.

cputime

float

Total CPU time used since the beginning of the session. This value cannot be set.

cputype

string

A string describing the CPU type that the current version of Maple was built for.  This is most useful on APPLE_UNIVERSAL_OSX where there are multiple possible CPU types for the same value of kernelopts( system ).

dagtag

name or integer

This option is more like a function in that it always requires a value and always returns a value. If the value is an integer, a name is returned. If the value is a name, an integer is returned. This facility is used to map between internal data structure ID numbers and their names. (See the assemble function.)

datadir

string

Location of the data directory containing auxiliary files such as text files, XML Schemas, and DTDs. Cannot be set.

datalimit

integer

The total amount of heap memory in kibibytes that Maple may consume. Maple aborts if this limit is exceeded. If the value is 0 or it is not given the current limit is returned. Limits may be raised or lowered. Maple limits may not be raised above system imposed hard limits. This option is not supported on all platforms. Values passed for this option can be given with a Unit of information.

dirsep

string

Returns the directory separator character for the architecture on which Maple is running. Cannot be set.

display_zero_complex_part

boolean

When set to false complex numbers of the form a+0*I are displayed without the 0*I part. The default value for this option is true.

filelimit

integer

The maximum number of files that Maple can have open at one time.  If the value is 0 or it is not given the current limit is returned. Important: This limit also affects internal Maple functions.

floatPi

boolean

Controls whether Pi is evaluated to a floating-point number when it is in an expression that contains other floating-point numbers. The default is true.

gcbytesavail

integer

Number of bytes available after the last invocation of garbage collection. This value cannot be set.

gcbytesreturned

integer

Number of bytes returned by the last invocation of garbage collection. This value cannot be set.

gcfreq

integer

Deprecated as of Maple 16.

gcmaxthreads

integer

The maximum number of threads Maple should use for the parallel garbage collector. The default is numcpus or 4, whichever is lower.

gcthreadmemorysize

integer

Maple determines how many threads to use for its parallel garbage collector by dividing number of bytes allocated, kernelopts(bytesalloc), by the value of gcthreadmemorysize, rounded up. The default value is 128 MiB.

gctimes

integer

Number of times that garbage collection has been invoked. This value cannot be set.

gctotaltime

float

The total amount of time spent performing garbage collections in CPU time.

gctotaltime[real]

float

The total amount of time spent performing garbage collections in real time.

gmpthreshold

integer

The threshold when the GNU Multiple Precision (GMP) library will be used for integer arithmetic. Maple represents all integers as either immediate or GMP integers. Therefore, kernelopts(maximmediate) may be more useful. kernelopts(gmpthreshold) is defined to be floor(log[10](kernelopts(maximmediate))). Thus, integers with greater than kernelopts(gmpthreshold) digits are represented as GMP integers. This value cannot be set.

gmpversion

string

The version of the GNU Multiple Precision (GMP) library used for long integer arithmetic. This value cannot be set.

heaps

table

Returns the type, starting address, ending address, the size in kibibytes of all the memory heaps currently used by the memory allocator and the thread identifier of the heap owner.  The types are one of thread-local, global or large.  Maple employs a multi-level allocator that distributes memory from different heap types based on the requested size. Allocations 4KB and less are serviced from a thread-local heap. Requests for blocks of memory greater than 4KB up to 1MB are handed out from the global heap.  Finally, blocks of memory greater than 1MB are individually allocated from a large heap unto themselves.

homedir

string

The path to the current user's home directory. This value cannot be set.

includepath

string or list

An ordered list of directories (separated by "," or ";") specifying the search path for included files. The initial value can be overridden by supplying an include path at the command line by using the -I option.  When modifying the include path via kernelopts, the path should not be prefixed with "-I". The maximum number of include path entries is 25.

inline

boolean

Specifies whether or not procedures with option inline are in-line expanded. The default value is true.

jvmheaplimit

integer

The total amount of heap memory, in kibibytes, the Java external calling virtual machine is allowed to use. This option is effective only if the limitjvmheap kernel option is true. Values passed for this option can be given with a Unit of information.

keepdebuginfo

boolean

If true (the default), debugging information stored in a procedure read from a library archive or source file is retained, allowing source level debugging (if the source code is available). If false, the debugging information is discarded.

level

integer

Internal depth of recursion/computation indicator. This value cannot be set.

limitjvmheap

boolean

If true, Maple limits the heap for the Java external calling virtual machine. The actual limit can be specified using the jvmheaplimit kernel option. The default value is false.

locale

string

The current locale (subset of environment settings that depend on language and cultural conventions) for localization. This value cannot be set.

mapledir

string

The path to the root of the Maple installation. This value cannot be set.

maxdigits

integer

The maximum allowable setting of Digits. This value cannot be set.

max_record_depth

integer

The maximum depth of nested Records that are displayed.

maximmediate

integer

The largest integer that can be represented in immediate-integer form (represented in a word, instead of a pointer to a multi-word data structure). Cannot be set.

memusage

list

Displays a matrix of memory usage by Maple internal objects. Each row contains the object type name, the number of objects of that type, and the number of bytes of storage occupied by such objects. Cannot be set.

multithreaded

boolean

Returns true if the current engine is multithreaded and false otherwise. Cannot be set.

numcpus

integer

Returns the number of CPUs that Maple will automatically optimize for.  By default this will be the actual number of CPUs that the machines has (treating hyperthreaded CPUs as 1 CPU).  This value can be set.

numactivethreads

integer

Returns the number of active threads.  An active thread is any thread that is executing code, and is not paused on a mutex or condition variable and is not waiting for another thread to finish.  The number of active threads can change at any time. Cannot be set.

opaquemodules

boolean

Specifies whether local members of a module are accessible outside the module. Setting this to false makes it easier to debug code that uses modules. The default value is true.

pathsep

string

Returns the path separator character for the architecture on which Maple is running. Cannot be set.

pid

integer

Returns the process ID of the kernel. Cannot be set.

platform

string

One of "unix" or "windows" depending on the underlying operating system. Note that for Mac OS X the platform is "unix". Use kernelopts(system) to distinguish Mac OS X from other "unix" subsystems. Cannot be set.

printbytes

boolean

Print the "bytes used.." message after every garbage collection (tty version). Default value is true.

'printlevel'

integer

An alternative interface to the printlevel environment variable. The default value is 1.

processlimit

integer

The maximum number of external processes that Maple can have running at one time. If the value is 0 or it is not given the current limit is returned.  Important: This limit also affects internal Maple functions.

profile

boolean

Produce resource information upon every call and exit from every function. The output is used as input for exprofile and excallgraph. The default is false.

readdotm

boolean

Read Maple .m files located in directories listed in libname. The default is false.

setsort

integer

Gives the current setting of the --setsort option provided on the command line.  See the maple help page for details. This value cannot be set.

shortlineinfo

boolean

When source file and line number information is displayed in error messages or during tracing, the full path of the source file is shown if this option is false. If set to true, only the actual file name of the source file is displayed.

sparse_sort_cutoff

integer

The number of inserts into a sparse rtable with hardware datatype before the index vectors are automatically resorted. The default value is 590.

stackalloc

integer

Total number of kibibytes of stack memory currently allocated by the Maple kernel. This value cannot be set.

stacklimit

integer

The total amount of stack space, in kibibytes that Maple may consume. Maple aborts if this limit is exceeded. If the value is 0 or it is not given the current limit is returned. Limits may be raised or lowered. Maple limits may not be raised above any system defined hard limits. This option is not supported on all platforms. Values passed for this option can be given with a Unit of information.

system

string

One of "APPLE UNIVERSAL OSX", "IBM INTEL LINUX", "IBM INTEL NT", "X86 64 WINDOWS" or "X86 64 LINUX" depending on the underlying operating system. Cannot be set.

toolboxdir

string

Returns the path to the first directory in the toolbox search path with the given name. When no value is specified, a list of all available toolbox paths is returned.

toolboxversion

string

Returns a list containing version information for each of the toolboxes installed on your system.  Each sublist in the result contains the toolbox feature name, the build date, and a build identifier. When a specific toolbox name is specified, the version information for only that toolbox is returned.

tracecatch

boolean

Activates tracing of caught exceptions. If true, then a notification is printed whenever an exception is caught by a catch statement. This notification indicates where the exception was caught, where it was thrown, and the exception message and arguments.

traceincidentalassign

boolean

If true, causes assignments that are side-effects of built-in functions to appear in trace output. See trace for more information.

tracelineinfo

integer

If non-zero, displays source file and line number information during tracing. See trace for more information.

traceshowspecassign

boolean

If true, causes some assignments shown during tracing to appear in a distinctive way. See trace for more information.

tracesplitmulassign

boolean

If true, causes multiple assignments shown during tracing to appear individually. See trace for more information.

unread

'symbol'

Marks the specified symbol as unread, meaning that the next access to that symbol will be re-read from the Maple library.

username

string

Returns the username of the user that is running the kernel. Cannot be set.

version

symbol

Version, compilation date, and build ID of the kernel. Cannot be set. For details on querying version information, see version.

versionnumber

string

Major version number of the kernel. This will be a string such as "2050" and will not include any minor version number extensions.

wordsize

integer

Returns the size of words (in bits) used by Maple data structures. This is usually 32 or 64. Cannot be set.

Thread Safety

• 

The kernelopts command is thread safe as of Maple 15, however different variables behave differently when set by multiple threads.

• 

The following variables have a global effect, thus the most recent setting of these variables will take effect.  Without explicit synchronization you may not be able to determine what settings are in effect at any particular time.

ASSERT

assertlevel

cacheclearlimit

cpulimit

datalimit

display_zero_complex_part

filelimit

floatPi

includepath

inline

max_record_depth

maxdigits

opaquemodules

printbytes

'printlevel'

processlimit

profile

readdotm

sparse_sort_cutoff

stacklimit

unread

• 

The following variables can be safely accessed from any thread:

bindir

byteorder

bytesalloc

bytesused

cputime

cputype

dagtag

datadir

dirsep

gcbytesavail

gcbytesreturned

gcmaxthreads

gcthreadmemorysize

gctimes

gctotaltime

gmpthreshold

gmpversion

heaps

homedir

inline

level

locale

mapledir

maxdigits

maximmediate

memusage

multithreaded

numcpus

numactivethreads

pathsep

pid

platform

stackalloc

stacklimit

system

toolboxdir

toolboxversion

username

version

wordsize

 

 

Examples

kerneloptsmaxdigits

38654705646

(1)

kerneloptswordsize

64

(2)

kerneloptsdagtag=4

FLOAT

(3)

kerneloptsdagtag=SERIES

15

(4)

kerneloptscputime

0.176812000000000

(5)

kerneloptsdatalimit=256Unitmegabyte:

kerneloptsdatalimit=256Unitmebibyte

250000

(6)

kerneloptsdatalimit=250000Unitkibibyte

262144

(7)

kerneloptsdatalimit

250000

(8)

kerneloptscpulimit=10Unitminute:

kerneloptscpulimit

600

(9)

π1.1

3.455751919

(10)

kerneloptsfloatPi=false:

π1.1

1.1π

(11)

Compatibility

• 

The tracelineinfo and shortlineinfo options are new in Maple 2020.

• 

The tracecatch option of debugopts was moved to kernelopts in Maple 2020.

• 

The kernelopts command was updated in Maple 2020.

See Also

assemble

debugopts

GMP

interface

trademark

Units of Information

Units package

version