class ProcessLimbo

Defined at line 3018 of file fidling/gen/sdk/fidl/fuchsia.exception/fuchsia.exception/hlcpp/fuchsia/exception/cpp/fidl.h

Protocol meant for clients interested in obtaining processes that are

suspended waiting for an exception handler (in limbo). This is the core

feature that enables Just In Time (JIT) debugging.

An example usage of this API would be having a debugger listen on limbo for

new processes. Then another component (eg. a CLI tool) could activate the

limbo, meaning that the system is now ready to capture crashing processes.

As the debugger got a notification that the limbo is now active, it can

correctly handle newly excepted processes and do its normal workflow.

Public Members

static const char[] Name_

Public Methods

void ~ProcessLimbo ()

void SetActive (bool active, SetActiveCallback callback)

Set the active state of the limbo. Will trigger the `WatchActive` event

if there was a change, meaning that any listening components will receive

a notification. This includes the caller of `SetActive`.

When a limbo is inactive, there will not be any processes waiting on it,

meaning that any waiting processes will be freed upon deactivating the

limbo.

void GetActive (GetActiveCallback callback)

Get whether the limbo is currently active. An active limbo could be empty

(not have any processes waiting on an exception). When a limbo is inactive,

there will not be any processes waiting on it.

void WatchActive (WatchActiveCallback callback)

Watch for changes determining whether the limbo is currently active,

using a Hanging Get pattern.

void ListProcessesWaitingOnException (ListProcessesWaitingOnExceptionCallback callback)

List processes that are waiting on exceptions.

Returns information on all the processes currently waiting on an exception.

The information provided will not contain any handle, so that it can be

transported over Overnet (see https://fxbug.dev/42182115).

The implementation should ensure that at any time there are no more than

MAX_EXCEPTIONS exceptions held in the limbo, so that no pagination is needed.

Returns ZX_ERR_UNAVAILABLE if limbo is not active.

void WatchProcessesWaitingOnException (WatchProcessesWaitingOnExceptionCallback callback)

Watch for processes that are waiting on exceptions, using a Hanging Get

Pattern.

Returns information on all the processes currently waiting on an exception.

The information provided is intended to correctly identify an exception

and determine whether the caller wants to actually handle it.

To retrieve an exception, use the `GetException` call.

Returns ZX_ERR_UNAVAILABLE if limbo is not active.

Returns ZX_ERR_CANCELED if there was an outstanding call and the limbo

becomes inactive.

NOTE: The `process` and `thread` handle will only have the ZX_RIGHT_READ

right, so no modification will be able to be done on them.

void RetrieveException (uint64_t process_koid, RetrieveExceptionCallback callback)

Removes the process from limbo and retrieves the exception handle and

associated metadata from an exception.

Use `ListProcessesWaitingOnException` to choose a `process_koid` from the

list of available exceptions.

Returns ZX_ERR_NOT_FOUND if the process is not waiting on an exception.

Returns ZX_ERR_UNAVAILABLE if limbo is not active.

void ReleaseProcess (uint64_t process_koid, ReleaseProcessCallback callback)

Removes the process from limbo, releasing the exception. This will make

it "bubble up" beyond the scope of of this limbo, making it

unretrievable in the future from here.

void AppendFilters (::std::vector< ::std::string> filters, AppendFiltersCallback callback)

Adds filters to the limbo. Filters determine what processes the limbo

will store when receiving an exception. Repeated filters will be

ignored. Filters work by "filtering out" processes. It means that if a

filter matches, that process won't get included.

Filters work by substring matching. This means that a process name has

to have the filter as a substring in order to match it. Example:

Filter = "dev".

Process = "process" won't match.

Process = "devcoordinator" will match.

Adding filters is transactional: either all of them go in, or none at

all. The maximum amount of filters is determined by

`MAX_FILTERS_PER_CALL`. If the maximum is exceeded, ZX_ERR_NO_RESOURCES

is returned.

Changing filters have no effect on processes that are currently waiting

on an exception, but rather which future processes that will remain in

the limbo.

Returns ZX_ERR_UNAVAILABLE if limbo is not active.

void RemoveFilters (::std::vector< ::std::string> filters, RemoveFiltersCallback callback)

Removes filters to the limbo. Any filters that are not currently present

on the limbo will be ignored.

Returns ZX_ERR_UNAVAILABLE if limbo is not active.

void GetFilters (GetFiltersCallback callback)

Returns filters that are currently active within the limbo. If the limbo

is inactive, it will return an empty vector.