Lifecycle functions (C++ SDK)

Lifecycle functions inform the Antithesis environment that particular test phases or milestones have been reached. They are part of the Antithesis C++ SDK.

Both functions accept a details object for additional contextual information. It can be omitted from setup_complete; send_event requires an object.

Functions

Setup

void setup_complete()
void setup_complete(const JSON& details)

Indicates to Antithesis that setup has completed. Call this function when your system and workload are fully initialized. After this function is called, Antithesis will take a snapshot of your system and begin injecting faults.

Calling this function multiple times or from multiple processes will have no effect. Antithesis will treat the first time any process called this function as the moment that the setup was completed.

The function is called using the Antithesis namespace:

antithesis::setup_complete();
antithesis::setup_complete({{"nodes", 3}});

Parameters

details
Optional contextual information. Call antithesis::setup_complete() when there is no additional context; the emitted setup record will have no details field. Calling antithesis::setup_complete({}) explicitly records an empty details object.

See Details for the object format.

Send event

void send_event(const char* name, const JSON& details)

This causes an event with the name and details provided to be sent to the Antithesis platform. This is analogous to logging an event, and may be slightly preferable because (1) the event is structured JSON, and (2) the timing of the event is much more precise with respect to your assertions, so debugging may be slightly easier for issues where exact timing matters for diagnosing a problem.

The function is called using the Antithesis namespace:

antithesis::send_event("checkpoint", {});
antithesis::send_event("progress", {{"completed", 42}});

Parameters

name
const char*. The name of the event that you are logging. This name will appear in the logs section of a triage report.

details
The event payload. This argument is required: pass {} for an event without additional context. For example, antithesis::send_event("checkpoint", {}) emits {"checkpoint": {}}.

See Details for the object format.

Common parameters

Details

antithesis::JSON extends std::map<std::string, antithesis::JSONValue>. JSONValue is a std::variant supporting scalar values, nested JSON objects, and arrays.

Both functions borrow existing objects and serialize them synchronously without copying nested values. Constructing an object at the call site still incurs its construction cost.

You can specify details using initialization syntax:

{
    {"name", "Bob"},
    {"number", 123.4}
}

You can also include nested JSON in details, which requires the identifier antithesis::JSON:

{
    {"nested", antithesis::JSON{
                                    {"a", "b"},
                                    {"c", 1234}
                                }
    }
}