Random functions (C++ SDK)

Random functions

Random functions request both structured and unstructured randomness from the Antithesis platform. They are part of the Antithesis C++ SDK.

These functions should not be used to seed a conventional PRNG, and should not have their return values stored and used to make a decision at a later time. Doing either of these things makes it much harder for the Antithesis platform to control the history of your program’s execution, and also makes it harder for Antithesis to learn which inputs, provided at which times, are most fruitful. Instead, you should call a function from the random package every time your program or test template needs to make a decision – at the moment that you need to make the decision.

These functions are also safe to call outside the Antithesis environment, where they will fall back on values from the standard library’s random. If you want to override this default behavior, then #define ANTITHESIS_RANDOM_OVERRIDE. If this is defined, then the SDK will use the provided function when run locally. (This setting is ignored when run in the Antithesis environment.)

To use this override, define ANTITHESIS_RANDOM_OVERRIDE before including antithesis_sdk.h:

#define ANTITHESIS_RANDOM_OVERRIDE my_random
#include "antithesis_sdk.h"

 // ...

uint64_t my_random() {
    // Do something and return a random number
}

Functions

Get random

uint64_t get_random()

Returns a uint64_t value chosen by Antithesis. You should not store this value or use it to seed a PRNG, but should use it immediately.

The function is called using the Antithesis namespace: antithesis::get_random()

Random choice

template <typename Iter>
Iter random_choice(Iter begin, Iter end)

Returns a randomly chosen item from a list of options. You should not store this value but should use it immediately. Internally, this function gets its randomness from get_random().

This function is not purely for convenience. Signaling to the Antithesis platform that you intend to use a random value in a structured way enables it to provide more interesting choices over time.

The function is called using the Antithesis namespace: antithesis::random_choice(begin, end)

Template parameters

Iter
Iter should be a random-access iterator type.

Example

std::string in {"ABCDEFGHIJK"};
char random_character = *antithesis::random_choice(in.begin(), in.end());
  • Introduction
  • How Antithesis works
  • Get started
  • Test an example system
  • With Docker Compose
  • Build and run an etcd cluster
  • Meet the Test Composer
  • With Kubernetes
  • Build and run an etcd cluster
  • Meet the Test Composer
  • Setup guide
  • For Docker Compose users
  • For Kubernetes users
  • Product
  • Test Composer
  • Test Composer basics
  • Test Composer reference
  • How to check test templates locally
  • How to port tests to Antithesis
  • Reports
  • The triage report
  • Findings
  • Environment
  • Utilization
  • Properties
  • The bug report
  • Context, Instance, & Logs
  • Bug likelihood over time
  • Statistical debug information
  • Search dashboard & multiverse map
  • Multiverse debugging
  • Overview
  • The Antithesis multiverse
  • Querying with event sets
  • Environment utilities
  • Using the Antithesis Notebook
  • Cookbook
  • Tooling integrations
  • CI integration
  • Discord and Slack integrations
  • Issue tracker integration - BETA
  • Configuration
  • Access and authentication
  • The Antithesis environment
  • Optimizing for Antithesis
  • Docker best practices
  • Kubernetes best practices
  • Concepts
  • Properties and Assertions
  • Properties in Antithesis
  • Assertions in Antithesis
  • Sometimes Assertions
  • Properties to test for
  • Fault injection
  • Reference
  • Webhooks
  • Launching a test in Docker environment
  • Launching a test in Kubernetes environment
  • Launching a debugging session
  • Retrieving logs
  • SDK reference
  • Go
  • Tutorial
  • Instrumentor
  • Assert (reference)
  • Lifecycle (reference)
  • Random (reference)
  • Java
  • Tutorial
  • Instrumentation
  • Assert (reference)
  • Lifecycle (reference)
  • Random (reference)
  • C
  • C++
  • Tutorial
  • C/C++ Instrumentation
  • Assert (reference)
  • Lifecycle (reference)
  • Random (reference)
  • JavaScript
  • Python
  • Tutorial
  • Assert (reference)
  • Lifecycle (reference)
  • Random (reference)
  • Rust
  • Tutorial
  • Instrumentation
  • Assert (reference)
  • Lifecycle (reference)
  • Random (reference)
  • .NET
  • Tutorial
  • Instrumentation
  • Assert (reference)
  • Lifecycle (reference)
  • Random (reference)
  • Languages not listed above
  • Assert (reference)
  • Lifecycle (reference)
  • Assertion Schema
  • Instrumentation
  • Handling external dependencies
  • FAQ
  • Product FAQs
  • About Antithesis POCs
  • Release notes
  • Release notes