Provides various ways of waiting for things to happen.

Overview

Elixir is a functional programming language with an emphasis on immutability of data. However, when dealing with shared state or interacting with external systems, change happens.

WaitForIt provides various ways of waiting for such changes to happen.

While Elixir provides several language and standard library features (such as Process.sleep/1, receive/1/after, and Task.async/1/Task.await/2) that can be used to implement waiting, they are inconvenient to use for this purpose. WaitForIt builds on top of these language features to provide convenient and easy-to-use facilities for waiting on specific conditions. While this is likely most useful for test code in which tests must wait for concurrent or asynchronous activities to complete, it is also useful in any scenario where concurrent processes must coordinate their activity. Examples include asynchronous event handling, producer-consumer processes, and time-based activity.

This page doubles as the API reference and an introduction. If you are just getting started, the task-focused guides walk through the most common scenarios: Waiting in tests, Polling vs signaling, Composing waits, Recipes, and Telemetry.

Quick start

To use WaitForIt, you must first require WaitForIt or import WaitForIt.

There are five distinct forms of waiting provided. Jump to the docs for each for more information.

wait

The wait/2 macro waits until a given expression evaluates to a truthy value.

# Wait up to one minute for a file to exist, and then print its contents
if WaitForIt.wait(File.exists?("data.csv"), timeout: :timer.minutes(1)) do
  IO.puts(File.read!("data.csv"))
else
  IO.warn("Stopped waiting for the file to exist")
end

match_wait

The match_wait/3 macro waits until a given expression matches a given pattern, and binds out of it. It is the most convenient form when waiting for a tagged result such as {:ok, value}.

# Wait up to two seconds for a record to exist, binding it directly.
{:ok, user} = WaitForIt.match_wait({:ok, %User{}}, Repo.fetch(User, id), timeout: 2_000)

case_wait

The case_wait/3 macro waits until a given expression evaluates to a value that matches any one of the given case clauses. It looks and acts like an Elixir case/2 expression except that it can take an optional else clause.

# Wait for 30 seconds for a directory to exist, and then write a file in it
WaitForIt.case_wait(File.stat("data"), timeout: :timer.seconds(30)) do
  {:ok, %File.Stat{type: :directory}} ->
    File.write!("data/greeting.txt", "Hello, world!")
else
  {:ok, %File.Stat{type: type}} ->
    IO.warn("Expected 'data' to be a directory but its type is #{inspect(type)}")

  {:error, reason} ->
    IO.warn("Could not stat 'data': #{inspect(reason)}")
end

cond_wait

The cond_wait/2 macro waits until any one of the given expressions evaluates to a truthy value. It looks and acts like an Elixir cond/1 expression except that it can take an optional else clause.

# Wait for up to one minute for either a specific file to exist OR for the top of the minute
# to be reached.
WaitForIt.cond_wait(timeout: :timer.seconds(10), interval: 500) do
  File.exists?("data/process.json") ->
    IO.puts("Processing...")

  NaiveDateTime.utc_now().second == 0 ->
    IO.puts("Processing...")
else
  IO.warn("Stopped waiting since neither condition ever became truthy")
end

with_wait

The with_wait/3 macro composes several waits in a pipeline. It looks and acts like an Elixir with/1 expression, except that its <~ clauses wait until their expression matches.

# Wait for an account to load, then for its balance, short-circuiting to else on timeout.
WaitForIt.with_wait on(
  {:ok, account} <~ {load_account(token), timeout: 2_000},
  {:ok, balance} <~ fetch_balance(account)
) do
  {:ok, balance}
else
  not_ready -> {:error, {:timed_out, not_ready}}
end

Options

All forms of waiting accept the same set of options to control their behavior:

• :timeout - the amount of time to wait (in milliseconds) before giving up (default: 5_000)
• :pre_wait - wait for the given number of milliseconds before evaluating conditions for the first time (default: 0)
• :interval - the polling interval (in milliseconds) at which to re-evaluate conditions (default: 100)
• :signal - disable polling and use a signal of the given name instead

See Polling-based waiting for more information on the :interval option and Signal-based waiting for more information on the :signal option.

Timeout behavior

The forms of waiting differ in what happens when a wait times out. This table summarizes the behavior; the non-bang forms mirror the corresponding built-in Elixir construct, while every bang form raises a WaitForIt.TimeoutError.

Waitable expressions and waiting conditions

Waitable expressions and waiting conditions are fundamental concepts in WaitForIt.

A waitable expression is any arbitrary Elixir expression that can be evaluated one or more times to produce a value.

A waiting condition is a conditional expression that indicates whether waiting should continue or be halted with a particular value.

In the case of wait/2, there is a single waitable expression, which is passed as the first argument of the macro, and an implicit waiting condition, which is based on the truthiness of the associated waitable expression. For example:

WaitForIt.wait(2 + 2 == 5, timeout: 200)

In this example the waitable expression is 2 + 2 == 5 and the implicit waiting condition is the truthiness of that expression. The waitable expression is repeatedly evaluated until the value that it produces satisfies the waiting condition. In this case, the value of evaluating the expression is always false so it will never satisfy the waiting condition of a truthy value, and will therefore result in a timeout.

For case_wait/3, there is a single waitable expression and one or more explicit waiting conditions expressed as case clauses. For example:

WaitForIt.case_wait(File.stat("data.csv"), timeout: :timer.seconds(10)) do
  {:ok, %File.Stat{} = file_stat} -> IO.inspect(file_stat)
end

In this example the waitable expression is File.stat("data.csv"), which, upon evaluation, results in a value of either {:ok, %FileStat{}} or {:error, reason}. There is also one explicit waiting condition, which is the case clause {:ok, %File.Stat{} = file_stat}. The waitable expression will be repeatedly evaluated until it produces a value satisfying the lone waiting condition. In other words, it will wait until the file exists or a timeout occurs.

For cond_wait/2, there can be one or more waitable expressions and each one is paired with an implicit waiting condition, which is the truthiness of the waitable expression value. For example:

WaitForIt.cond_wait(timeout: :timer.hours(1)) do
  Date.utc_today().day == 1 -> IO.puts("It's the first day of the month")
  NaiveDateTime.utc_now().minute == 30 -> IO.puts("It's half past the hour")
end

In this example, there are two waitable expressions: Date.utc_today().day == 1 and NaiveDateTime.utc_now().minute == 30. Each of these is paired with an implicit waiting condition, which is the truthiness of the value produced by evaluating the expression.

Idempotency of waitable expressions

Waitable expressions are by their nature subject to change with repeated evaluations over time. Therefore, idempotent expressions are of little use in the context of waiting, since waiting would either halt immediately (if the expression already satisfies the waiting conditions) or never halt at all (if it does not satisfy the waiting conditions).

For this reason, it is expected that the value produced by waitable expressions may change on each re-evaluation, and that it is possible for each re-evaluation to produce side-effects. It is important, however, that any side-effects that can occur during evaluation of the expression are safe and predictable, since the expression may be evaluated an indeterminate number of times while waiting.

Polling-based waiting

By default, WaitForIt uses a polling-based waiting mode in which waitable expressions are periodically re-evaluated until waiting conditions have been met or a timeout has occurred. The interval at which waitable expressions are evaluated can be controlled by the :interval option, which specifies the delay between evaluations in milliseconds and is supported by all forms of waiting. (The legacy alias :frequency is also accepted; see the Options section.)

The :interval option may also be a 1-arity function of the attempt number, which enables backoff strategies — for example, polling less aggressively as time goes on so as not to hammer a struggling dependency. See WaitForIt.Backoff for ready-made strategies such as exponential backoff with jitter.

Signal-based waiting

Signal-based waiting obviates the need for polling by using a signaling mechanism to indicate that waiting conditions should be re-evaluated in response to some event. With signal-based waiting, instead of periodically re-evaluating conditions at a particular frequency, a signal is sent to waiters to indicate when waiting conditions should be re-evaluated. It is expected that the signal/1 function will be used to unblock the waiting code in order to re-evaluate the waiting conditions.

To use signal-based waiting instead of polling-based waiting use the :signal option that is supported by all forms of waiting. The value of the :signal option is an arbitrary term (typically an atom or a tuple of atoms) that serves as the binding between the waiting conditions and the asynchronous code that can alter the outcome of those waiting conditions. When the :signal option is used, WaitForIt will automatically wait until a matching signal is received and then re-evaluate waiting conditions. If the waiting conditions are satisfied then the wait is halted, if not then the wait continues until the next signal is received or a timeout occurs.

By way of example, imagine a typical producer-consumer problem in which a consumer process waits for items to appear in some buffer while a separate producer process occasionally places items in the buffer. In this scenario, the consumer process might use the wait/2 macro with the :signal option to wait until there are some items in the buffer and the producer process would use the signal/1 function to tell the consumer that it might be time for it to check the buffer again.

# CONSUMER process
WaitForIt.wait Buffer.count() >= 4, signal: :wait_for_buffer

# PRODUCER process
# put some things in buffer, then signal waiters
Buffer.put(1)
Buffer.put(2)
WaitForIt.signal(:wait_for_buffer)

Notice that the same signal name, :wait_for_buffer, is used by both the consumer and the producer, which is what allows the producer to signal to the consumer that waiting conditions should be re-evaluated. It is important to realize that just because a signal has been emitted does not necessarily mean that any waiting conditions have been satisfied. Rather, a signal indicates that waiters should re-evaluate their waiting conditions to determine if they should continue to wait or not.

See the Polling vs signaling guide for guidance on choosing between the two modes.

Telemetry

Every wait emits :telemetry events under the [:wait_for_it, :wait] prefix — :start, :stop, and :exception — so you can observe how long waits take, how many evaluations they require, and how often they time out. The :stop event reports the wait duration, the number of evaluations, and whether the wait :matched or hit a :timeout.

See the Telemetry guide for the full measurement and metadata reference, plus examples of attaching handlers and wiring up Telemetry.Metrics.

Using WaitForIt in tests

Tests — especially integration and end-to-end tests — are one of the most common places to wait on asynchronous work. The WaitForIt.Test module provides ExUnit assertions (assert_eventually/2, refute_eventually/2, and assert_always/2) that wait and re-evaluate and, on timeout, fail with a regular ExUnit.AssertionError that includes the source expression and the last value seen:

defmodule MyApp.SomeTest do
  use ExUnit.Case
  use WaitForIt.Test

  test "the user is eventually confirmed" do
    assert_eventually {:ok, %User{confirmed: true}} = Repo.fetch(User, user_id)
  end
end

The waiting macros described above can also be used directly in tests when you want their exact return values or timeout semantics — wait/2, for example, returns its value and so drops straight into an assert.

See the Waiting in tests guide for a full walkthrough.

A note on "catch-all" clauses

It is common to include "catch-all" clauses in normal Elixir case/2 and cond/1 expressions. Often, a case/2 expression will include a final catch-all clause (like _) which will always match. Similarly, a cond/1 expression will typically include a final always-truthy condition (like true) which will always match.

When using the waiting variants of these constructs, case_wait/3 and cond_wait/2, it is not recommended to use such catch-all clauses. The reason for this is that, since catch-all clauses by definition always match, including one as a waiting condition would not allow for re-evaluating any other waiting conditions and would terminate the wait immediately after the first evaluation.

Instead of using a catch-all clause that always matches, an else clause can be used instead. Unlike catch-all clauses, an else clause is only evaluated if there is a timeout during the associated waiting operation. Both case_wait/3 and cond_wait/2 support else clauses, which allows for customizing the behavior and return value of the expression in the event of a timeout.