Skip to content

Stack Trace Rt

Spice
1
import "std/runtime/stack_trace_rt";

StackTraceEntry struct

One frame of a stack trace.

Fields

Name Type Description
address byte* return address within the function
offset unsigned long bytes from the start of that function, 0 if unresolved
functionName String demangled, empty if the symbol could not be resolved
fileName String source file, empty unless the program carries debug info
lineNumber unsigned int line within that file, 0 if unknown
isSpice bool Spice code, as opposed to C, C++ or other native code; false if it could not be told

Methods

dump

Spice
1
public p StackTraceEntry.dump(unsigned long frameIndex, bool includeAddress = true)

Prints this frame to stderr, as '#

+ 0x at :'. The location is left out when the program carries no debug info; frames whose symbol could not be resolved print '' in place of the name and carry no offset.

Parameters

Name Type Description
frameIndex unsigned long Position of this frame in its trace, counted from the most recent call
includeAddress bool Whether to print the raw address. Pass false for deterministic output - addresses move between runs under ASLR/PIE. (default: true)

StackTrace struct

Implements: IIterable<StackTraceEntry>

A captured stack trace: the frames of one call stack, most recent call first.

Methods

getSize

Spice
1
public inline f<long> StackTrace.getSize()

Retrieve number of frames in this trace.

Returns: long — Number of frames

isEmpty

Spice
1
public inline f<bool> StackTrace.isEmpty()

Check if this trace is empty.

Returns: bool — Empty or not

getEntry

Spice
1
public inline f<StackTraceEntry&> StackTrace.getEntry(unsigned long index)

Retrieve frame at the given index, counted from the most recent call.

Parameters

Name Type Description
index unsigned long

Returns: StackTraceEntry& — Frame at the given index

capture

Spice
1
public p StackTrace.capture(unsigned int skipFrames = 0u)

Captures the stack of the calling function, resolving each frame as it goes. In an optimized build a function that was inlined into another still gets a frame of its own, since libbacktrace recovers it from the debug info; its offset is then counted from the start of the function it was inlined into.

Parameters

Name Type Description
skipFrames unsigned int Frames to omit above the direct caller, for wrappers that capture on a caller's behalf (default: 0u)

dump

Spice
1
public p StackTrace.dump(bool includeAddresses = true, bool hideNonSpiceFrames = false)

Prints the whole trace to stderr, one line per frame, numbered from '#0' at the most recent call. A no-op when nothing was captured.

Parameters

Name Type Description
includeAddresses bool Forwarded to StackTraceEntry.dump() (default: true)
hideNonSpiceFrames bool Leave out the frames that are not Spice code (see StackTraceEntry.isSpice), such as the C runtime below main. The frames that remain keep the number they have in the trace, so a gap in the numbering marks where frames were hidden, and every number still matches getEntry(). (default: false)

getIterator

Spice
1
public f<StackTraceIterator<StackTraceEntry>> StackTrace.getIterator()

Retrieve a forward iterator over the frames of this trace, so it can be walked with a foreach loop

Returns: StackTraceIterator<StackTraceEntry>

StackTraceIterator<T> struct

Implements: IIterator<StackTraceEntry>

Iterator over the frames of a stack trace, most recent call first.

A trace hands this out rather than the iterator of the Vector it currently keeps its frames in, so that how a trace stores them stays its own business. 'T' is always StackTraceEntry - see the type definitions at the top of this file for why it is spelled as a generic argument at all.

Constructors

ctor

Spice
1
public p StackTraceIterator.ctor(StackTrace& trace)

Construct a stack trace iterator over the given trace

Parameters

Name Type Description
trace StackTrace& Stack trace to iterate over

Methods

get

Spice
1
public inline f<StackTraceEntry&> StackTraceIterator.get()

Returns the current frame of the trace

Returns: StackTraceEntry& — Reference to the current frame

getIdx

Spice
1
public inline f<Pair<unsigned long, StackTraceEntry&>> StackTraceIterator.getIdx()

Returns the current frame number and the current frame of the trace

Returns: Pair<unsigned long, StackTraceEntry&> — Pair of current frame number and reference to the current frame

isValid

Spice
1
public inline f<bool> StackTraceIterator.isValid()

Check if the iterator is valid

Returns: bool — true or false

next

Spice
1
public inline p StackTraceIterator.next()

Moves the cursor to the next frame

Functions

sGetStacktrace

Spice
1
public f<StackTrace> sGetStacktrace()

Returns the calling function's stack trace. Auto-imported like the other 's'-prefixed runtime functions, so it needs no explicit import.

Returns: StackTrace

sDumpStacktrace

Spice
1
public p sDumpStacktrace(bool includeAddresses = true, bool hideNonSpiceFrames = false)

Captures and immediately dumps the calling function's stack trace to stderr. The compiler calls it, with the default arguments, at every panic and failed assertion, right before the program exits.

Capturing and printing a trace use the std, and a panic raised in there (say, running out of memory for a String) would come back here and start over, until the stack is used up. A call made while a dump is under way therefore prints nothing, which lets that panic end the program as it would without stack traces. The flag is not atomic, so two threads dumping at the same time may cost one of them its trace, or let a nested panic through.

Parameters

Name Type Description
includeAddresses bool Forwarded to StackTrace.dump() (default: true)
hideNonSpiceFrames bool Forwarded to StackTrace.dump() (default: false)

Operators

operator[]

Spice
1
public inline f<StackTraceEntry&> operator[](StackTrace& trace, unsigned long index)

Retrieve frame at the given index, counted from the most recent call.

Parameters

Name Type Description
trace StackTrace&
index unsigned long

Returns: StackTraceEntry& — Frame at the given index

operator++

Spice
1
public inline p operator++<T>(StackTraceIterator<T>& it)

Advances the cursor by one

Parameters

Name Type Description
it StackTraceIterator<T>& StackTraceIterator

operator--

Spice
1
public inline p operator--<T>(StackTraceIterator<T>& it)

Move the cursor back by one

Parameters

Name Type Description
it StackTraceIterator<T>& StackTraceIterator

operator+=

Spice
1
public inline p operator+=<T, Numeric>(StackTraceIterator<T>& it, Numeric offset)

Advances the cursor by the given offset

Parameters

Name Type Description
it StackTraceIterator<T>& StackTraceIterator
offset Numeric Offset

operator-=

Spice
1
public inline p operator-=<T, Numeric>(StackTraceIterator<T>& it, Numeric offset)

Move the cursor back by the given offset

Parameters

Name Type Description
it StackTraceIterator<T>& StackTraceIterator
offset Numeric Offset