jepsen.generator — jepsen 0.1.14

Generates operations for a test. Generators are composable, stateful objects which emit operations for processes until they are exhausted, at which point they return nil. Generators may sleep when generating operations, to delay the rate at which the test proceeds

Generators do not have to emit a :process for their operations; test workers will take care of that.

Every object may act as a generator, and constantly yields itself.

Big ol box of monads, really.

*threads* clj

The ordered collection of threads which will execute a particular generator. The special thread :nemesis is used for the nemesis; other threads are 0-n, where n is the test concurrency. Processes map to threads: process mod n is the thread ID.

The set of threads is used where multiple parts of a test must synchronize.

await clj

(await f)

(await f gen)

Blocks until the given fn returns, then allows [gen] to proceed. If no gen is given, yields nil. Only invokes fn once.

barrier clj

(barrier gen)

When the given generator completes, synchronizes, then yields nil.

cas clj

Random cas/read ops for a compare-and-set register over a small field of integers.

clients clj

(clients client-gen)

Executes generator only on clients.

concat clj

(concat & sources)

Takes n generators and yields the first non-nil operation from any, in order.

defgenerator clj macro

(defgenerator name fields print-forms & protocols-and-functions)

Like deftype, but the fields spec is followed by a vector of expressions which are used to print the datatype, and the Generator protocol is implicit. For instance:

(defgenerator Delay [dt]
  [(str dt " seconds")] ; For pretty-printing
  (op [this test process] ; Function body
    ...))

Inside the print-forms vector, every occurrence of a field name is replaced by (.some-field a-generator), so don't get fancy with let bindings or anything.

delay clj

(delay dt gen)

Every operation from the underlying generator takes dt seconds to return.

delay-fn clj

(delay-fn f gen)

Every operation from the underlying generator takes (f) seconds longer.

delay-til clj

(delay-til dt gen)

(delay-til dt precache? gen)

Operations are emitted as close as possible to multiples of dt seconds from some epoch. Where delay introduces a fixed delay between completion and invocation, delay-til attempts to schedule invocations as close as possible to the same time. This is useful for triggering race conditions.

If precache? is true (the default), will pre-emptively request the next operation from the underlying generator, to eliminate jitter from that generator.

derefer clj

(derefer dgen)

Sometimes you need to build a generator not now, but later; e.g. because it depends on state that won't be available until the generator is actually invoked. Wrap a derefable returning a generator in this, and it'll be deref'ed every time an op is requested. For instance:

(derefer (delay (gen/once {:type :drain-key, :value @key})))

Looks up the key to drain only once an operation is requested.

drain-queue clj

(drain-queue gen)

Wraps a generator, and keeps track of the balance of :enqueue and :dequeue operations that pass through. When the underlying generator is exhausted, emits enough :dequeue operations to dequeue every attempted enqueue.

each clj macro

(each gen-expr)

Takes an expression evaluating to a generator. Captures that expression as a function, and constructs a generator that invokes that expression once for each process, as new processes arrive, such that each process sees an independent copy of the underlying generator.

each- clj

(each- gen-fn)

Takes a function that yields a generator. Invokes that function to create a new generator for each distinct process.

f-map clj

(f-map f-map g)

Takes a function f-map converting op functions (:f op) to other functions, and a generator g. Returns a generator like g, but where fs are replaced according to f-map. Useful for composing generators together for use with a composed nemesis.

filter clj

(filter f gen)

Takes a generator and yields a generator which emits only operations satisfying (f op).

Generator clj protocol

op clj

(op gen test process)

Yields an operation to apply.

limit clj

(limit n gen)

Takes a generator and returns a generator which only produces n operations.

log clj

(log msg)

Logs a message only once, and yields nil.

log* clj

(log* msg)

Logs a message every time invoked, and yields nil.

map clj

(map f g)

A generator which wraps another generator g, transforming operations it generates with (f op test process), of if that fails, (f op). When the underlying generator yields nil, this generator also returns nil.

mix clj

(mix gens)

A random mixture of operations. Takes a collection of generators and chooses between them uniformly. If the collection is empty, generator returns nil.

nemesis clj

(nemesis nemesis-gen)

(nemesis nemesis-gen client-gen)

Combines a generator of normal operations and a generator for nemesis operations into one. When the process requesting an operation is :nemesis, routes to the nemesis generator; otherwise to the normal generator.

next-tick-nanos clj

(next-tick-nanos anchor dt)

(next-tick-nanos anchor dt now)

Given a period dt (in nanos), beginning at some point in time anchor (also in nanos), finds the next tick after time now, such that the next tick is separate from anchor by an exact multiple of dt. If now is omitted, defaults to the current time.

on clj

(on f source)

once clj

(once source)

Wraps another generator, invoking it only once.

op-and-validate clj

(op-and-validate gen test process)

Wraps op to ensure we produce a valid operation for our worker. Re-throws any exception we catch from the generator.

phases clj

(phases & generators)

Like concat, but requires that all threads finish the first generator before moving to the second, and so on.

process->node clj

(process->node test process)

Given a test and a process identifier, returns the corresponding node this process is likely (clients aren't required to respect the node they're given) talking to, if process is an integer. Otherwise, nil.

process->thread clj

(process->thread test process)

Given a process identifier, return the corresponding thread identifier.

process-limit clj

(process-limit n gen)

Takes a generator and returns a generator with bounded concurrency--it emits operations for up to n distinct processes, but no more. Once n+1 processes have requested an operation, emits nil forever.

queue clj

(queue)

A random mix of enqueue/dequeue operations over consecutive integers.

reserve clj

(reserve & args)

Takes a series of count, generator pairs, and a final default generator.

(reserve 5 write 10 cas read)

The first 5 threads will call the write generator, the next 10 will emit CAS operations, and the remaining threads will perform reads. This is particularly useful when you want to ensure that two classes of operations have a chance to proceed concurrently--for instance, if writes begin blocking, you might like reads to proceed concurrently without every thread getting tied up in a write.

Rebinds threads appropriately. Assumes that every invocation of this generator arrives with the same binding for threads.

seq clj

(seq coll)

Given a sequence of generators, emits one operation from the first, then one from the second, then one from the third, etc. If a generator yields nil, immediately moves to the next. Yields nil once coll is exhausted.

seq-all clj

(seq-all coll)

Given a sequence of generators, emits all operations from the first, then all operations from the second, then all from the third, etc. If a generator yields nil, immediately moves to the next. Yields nil once all generators in coll are exhausted.

Be aware that providing an infinite sequence of generators to seq-all may result in an infinite loop, if every generator returns nil immediately. Ensure that at least some, if not all, generators in an infinite sequence actually return operations. You don't want to seq-all over an infinite sequence of the same stateful, limited generators; when those generators are exhausted, you'll create an infinite loop going through each of them, obtaining nil, and moving to the next.

singlethreaded clj

(singlethreaded gen)

Obtaining an operation from the underlying generator requires an exclusive lock. TODO: is this actually used by anyone? Feels kind of silly given everythng else is concurrency-safe.

sleep clj

(sleep dt)

Takes dt seconds, and always produces a nil.

sleep-nanos clj

(sleep-nanos dt)

High-resolution sleep; takes a (possibly fractional) time in nanos.

sleep-til-nanos clj

(sleep-til-nanos t)

High-resolution sleep; takes a time in nanos, relative to System/nanotime.

stagger clj

(stagger dt gen)

Introduces uniform random timing noise with a mean delay of dt seconds for every operation. Delays range from 0 to 2 * dt.

start-stop clj

(start-stop t1 t2)

A generator which emits a start after a t1 second delay, and then a stop after a t2 second delay.

synchronize clj

(synchronize gen)

Blocks until all nodes are blocked awaiting operations from this generator, then allows them to proceed. Only synchronizes a single time; subsequent operations on this generator proceed freely.

then clj

(then a b)

Generator B, synchronize, then generator A. Why is this backwards? Because it reads better in ->> composition.

time-limit clj

(time-limit dt source)

Yields operations from the underlying generator until dt seconds have elapsed.

void clj

A generator which terminates immediately

with-threads clj macro

(with-threads threads & body)

Binds threads for duration of body. Safety check: asserts threads are sorted.