This is an automatically generated page and cannot be edited directly. Text in Composite pages, (URLs starting with 'routine' or 'syntax') can be edited by clicking on the link labeled 'in context', and editing the text there.

Exit this popup by pressing <Escape>, or clicking on X or on the background.

snap
Combined from primary sources listed below.

In Telemetry§

See primary documentation in context for routine snap. 

multi snap(--> Nil)
multi snap(Str:D $message --> Nil)
multi snap(Str $message = "taking heap snapshot...", :$heap!)
multi snap(@s --> Nil)

The snap subroutine is shorthand for creating a new Telemetry object and pushing it to an array for later processing. The subroutine is exported by default.

From release 2017.11, one can give a custom array @s to push to:

use Telemetry;
my @s;
for ^5 {
    snap(@s);
    # do some stuff
    LAST snap(@s);
}

If no array is specified, it will use an internal array for convenience.

From release 2019.07, snap accepts a positional argument $message of type Str, which will become the value of the message attribute of the new Telemetry object.

Also from release 2019.07, one can pass a named argument :heap to instruct the compiler to write a heap snapshot to a file. From release 2021.12, snap returns that filename. The argument :heap can be of type Bool, Str, or IO::Path. Their implications are as follows:

  • IO::Path, e.g. snap( heap => 'outputfile'.IO ): The snapshot will be written to exactly this path. The returned filename is always an absolute path.

  • Str, e.g. snap(:heap<outputfile>): The snapshot will be written to this path if no such file already exists. If such a file already exists, the snapshot will instead be written to outputfile-$($*PID)-$($i).mvmheap (where $i starts at 1 and increases each time). The returned filename is a relative or an absolute path depending on what form :heap has.

  • Boolean True, e.g. snap(:heap): The snapshot will be written to the file heapsnapshot-$($*PID)-$($i).mvmheap. The returned filename is always a relative path.

Additionally, in each of these cases, two ordinary Telemetry objects are pushed to the internal array: One of them is created just before writing the snapshot and has $message as its message attribute. The other is created just after writing the snapshot and has the filename as ith message attribute.

Finally, there's also this option for :heap:

  • Boolean False, e.g. snap(:!heap): No heap snapshot is taken, no file is written. Instead, snap() will be called (or snap($message), if a custom $message has been specified).