silk.platform.native.diagnostics.

When to use#

silk.platform.native.start and silk.platform.wasi.start use it around the application. Use it in a custom runtime: make an observer with NativeDiagnostics.make, then wrap the application with NativeDiagnostics.observe.

Details#

While the body runs, the observer records the call path and the causes of errors in a pool of context nodes. When an error is handled, its nodes go back to the pool. When an error is not handled, the observer writes it with a NativeReport. If the pool is empty, the report still has the error name and its origin, but frames and causes can be missing.

Gotchas#

• The observer does not close the descriptor of the report, and does not end the process.

• An unhandled error gives status 1, also when the report cannot be written.

• A trap writes a report, then the program stops. In an unoptimized native build the report also names the functions that called the trapping one, without those of the standard library. A wasm program cannot walk its own stack, so the runtime's own trace lists the callers: Wasmtime's on WASI, the engine's Error.stack on wasm32-unknown-unknown.

Import as NativeDiagnostics with import silk.platform.native.diagnostics { NativeDiagnostics }.

Public declarations: 1.

NativeDiagnostics#

pub struct NativeDiagnostics

The observer of native and WASI programs that reports unhandled errors and traps, with their call path. It has a report writer and a pool of context nodes.

When to use#

silk.platform.native.start and silk.platform.wasi.start use it around the application. Use it in a custom runtime: make an observer with NativeDiagnostics.make, then wrap the application with NativeDiagnostics.observe.

Details#

While the body runs, the observer records the call path and the causes of errors in the pool. When an error is handled, its nodes go back to the pool. When an error is not handled, the observer writes it with a NativeReport. If the pool is empty, the report still has the error name and its origin, but frames and causes can be missing.

The report leaves out caller frames from the standard library (module paths that start with silk/), such as the runtime's own Effect.flatMap. The origin line is always written, also when the error was created in the standard library.

Each report starts with the full limits of the NativeReport, so one observer can write several reports. A handler that reports a handled error in its own words, such as the test runner for a failed expectation, calls Intrinsic.observeHandled after it: the observer then writes only the caller frames of that error.

Gotchas#

• The observer does not close the descriptor of the report, and does not end the process.

• An unhandled error gives status 1, also when the report cannot be written.

• A trap writes a report, then the program stops. In an unoptimized native build the report also names the functions that called the trapping one, without those of the standard library. A WASI program cannot walk its own stack, so the WASI runtime's own trace lists the callers.

Implementation NativeDiagnostics#

impl NativeDiagnostics

Associated function make#

pub effect fn make(report: NativeReport, capacity: usize) -> NativeDiagnostics

Returns an observer that writes with report, and has a pool of capacity context nodes.

Details#

It writes nothing. With a capacity of 0, it allocates no pool. If the allocation fails, the observer works without a pool.

Method observe#

pub fn observe<'env, A, ?R>(self: Self, body: once Effect<'env; A ? R>) -> once Effect<'env; A ? R>

Returns an effect that runs body under this observer.

Details#

It does not run body now. The observer is released when the effect completes, is cancelled, or is dropped before it runs. A suspended effect keeps it. The value and the requirements of body are unchanged. body must handle its own errors.

Gotchas#

In the handler of an unhandled error, drop the error value before you call Intrinsic.observeUnhandled. That call returns 1, also when the report cannot be written.

Category: Native platform.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, x86_64-unknown-linux-gnu, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2.