2.11.4 gcdict
Keywords: onyx

Next: 2.11.5 globaldict Up: 2.11 Dictionary reference Previous: 2.11.3 errordict Contents Index

##
2.11.4 gcdict

The gcdict dictionary provides garbage collection control and status capabilities.

Table 2.6: gcdict summary
Input(s) Op/Proc/Var Output(s) | Description
Control operators
- collect - | Force a garbage collection.
boolean setactive - | Set whether the garbage collector is active.
seconds setperiod - | Set the inactivity period before the garbage collector will run.
count setthreshold - | Set the number of bytes of memory allocation that will trigger a garbage collection.
State and statistics operators
- active boolean | Get whether the garbage collector is active.
- period seconds | Get the inactivity period before the garbage collector will run.
- threshold count | Get the number of bytes of memory allocation that will trigger a garbage collection.
- stats array | Get garbage collection statistics.

- active boolean:
  Input(s):
    None.
  Output(s):
    boolean:
      If true, the garbage collector is active; otherwise it is not active.
  Error(s):
    None.
  Description:
    Get whether the garbage collector is active.
  Example(s):

        onyx:0> gcdict begin active end 1 sprint
        false

- collect -:
  Input(s):
    None.
  Output(s):
    None.
  Error(s):
    None.
  Description:
    Force a garbage collection.
  Example(s):

        onyx:0> gcdict begin collect end
        onyx:0>

- period seconds:
  Input(s):
    None.
  Output(s):
    seconds:
      The minimum number of seconds since the last object allocation that the garbage collector will wait before doing a garbage collection. 0 is treated specially to mean forever.
  Error(s):
    None.
  Description:
    Get the minimum number of seconds of object allocation inactivity that the garbage collector will wait before doing a garbage collection. This setting is disjoint from the threshold setting, and does not prevent garbage collection due to the threshold having been reached.
  Example(s):

        onyx:0> gcdict begin period end 1 sprint
        60
        onyx:0>

boolean setactive -:
  Input(s):
    boolean:
      If true (initial setting), activate the garbage collector; otherwise deactivate the garbage collector.
  Output(s):
    None.
  Error(s):
    stackunderflow.
    typecheck.
  Description:
    Set whether the garbage collector is active. This setting takes effect asynchronously, so it is possible for the garbage collector to run even after it has been deactivated. This setting overrides the allocation inactivity period and allocation threshold settings, so that if this setting is set to false, the other settings have no effect.
  Example(s):

        onyx:0> gcdict begin false setactive end
        onyx:0>

seconds setperiod -:
  Input(s):
    seconds:
      The minimum number of seconds since the last object allocation that the garbage collector will wait before doing a garbage collection. 0 is treated specially to mean forever.
  Output(s):
    None.
  Error(s):
    stackunderflow.
    typecheck.
    limitcheck.
  Description:
    Set the minimum number of seconds of object allocation inactivity that the garbage collector will wait before doing a garbage collection. This setting is disjoint from the threshold setting, and does not prevent garbage collection due to the threshold having been reached.
  Example(s):

        onyx:0> gcdict begin 60 setperiod end
        onyx:0>

count setthreshold -:
  Input(s):
    count:
      Number of bytes of memory allocation since the last garbage collection that will trigger a garbage collection. 0 is treated specially to mean infinity.
  Output(s):
    None.
  Error(s):
    stackunderflow.
    typecheck.
    limitcheck.
  Description:
    Set the number of bytes of memory allocation since the last garbage collection that will trigger a garbage collection. This setting is disjoint from the inactivity period setting, and does not prevent garbage collection due to the allocation inactivity period having been exceeded.
  Example(s):

        onyx:0> gcdict begin 40000 setthreshold end
        onyx:0>

- stats array:
  Input(s):
    None.
  Output(s):
    array:
      An array with the format [collections count [ccount cmark] [mcount mmark] [scount smark]], where the fields have the following meanings:
      collections:
        Total number of collections the garbage collector has performed.
      count:
        Current number of bytes of memory allocated.
      ccount:
        Number of bytes of memory allocated as of the end of the most recent garbage collection.
      cmark:
        Number of microseconds taken by the most recent garbage collection mark phase.
      mcount:
        Largest number of bytes of memory ever allocated at any point in time.
      mmark:
        Maximum number of microseconds taken by any garbage collection mark phase.
      scount:
        Total number of bytes of memory ever allocated.
      smark:
        Total number of microseconds taken by all garbage collection mark phases.
  Error(s):
    None.
  Description:
    Get statistics about the garbage collector.
  Example(s):

        onyx:0> gcdict begin
        onyx:0> stats 2 sprint
        [28 280921 [118328 852] [904779 1007] [5707551 24205]]
        onyx:0>

- threshold count:
  Input(s):
    None.
  Output(s):
    count:
      Number of bytes of memory allocation since the last garbage collection that will trigger a garbage collection. 0 is treated specially to mean infinity.
  Error(s):
    None.
  Description:
    Get the number of bytes of memory allocation since the last garbage collection that will trigger a garbage collection. This setting is disjoint from the inactivity period setting, and does not prevent garbage collection due to the allocation inactivity period having been exceeded.
  Example(s):

        onyx:0> gcdict begin threshold end 1 sprint
        65536
        onyx:0>

Next: 2.11.5 globaldict Up: 2.11 Dictionary reference Previous: 2.11.3 errordict Contents Index