vmod_vtc

Utility module for varnishtest

Manual section

3

SYNOPSIS

import vtc [from “path”] ;

DESCRIPTION

The goal for this VMOD is to provide VCL users and VMOD authors means to test corner cases or reach certain conditions with varnishtest.

barrier_sync

VOID barrier_sync(STRING addr, DURATION timeout=0)

When writing test cases, the most common pattern is to start a mock server instance, a Varnish instance, and spin up a mock client. Those entities run asynchronously, and others exist like background processes (process) or log readers (logexpect). While you can synchronize with individual entities and wait for their completion, you must use a barrier if you need to synchronize two or more entities, or wait until a certain point instead of completion.

Not only is it possible to synchronize between test entities, with the barrier_sync function you can even synchronize VCL code:

sub vcl_recv {
    # wait for some barrier b1 to complete
    vtc.barrier_sync("${b1_sock}");
}

If the function fails to synchronize with the barrier for some reason, or if it reaches the optional timeout, it fails the VCL transaction.

MISCELLANEOUS

no_backend

BACKEND no_backend()

Fails at backend selection.

no_stevedore

STEVEDORE no_stevedore()

Fails at storage selection.

panic

VOID panic(STRING)

It can be useful to crash the child process in order to test the robustness of a VMOD.

sleep

VOID sleep(DURATION)

Block the current worker thread.

WORKSPACES

It can be useful to put a workspace in a given state when testing corner cases like resource exhaustion for a transaction, especially for VMOD development. All functions available allow to pick which workspace you need to tamper with, available values are client, backend, session and thread.

workspace_alloc

VOID workspace_alloc(ENUM {client,backend,session,thread}, INT size)

Allocate and zero out memory from a workspace. A negative size will allocate as much as needed to leave that many bytes free. The actual allocation size may be higher to comply with memory alignment requirements of the CPU architecture. A failed allocation fails the transaction.

workspace_free

INT workspace_free(ENUM {client,backend,session,thread})

Find how much unallocated space there is left in a workspace.

workspace_snapshot

VOID workspace_snapshot(ENUM {client,backend,session,thread})

Snapshot a workspace. Only one snapshot may be active at a time.

workspace_reset

VOID workspace_reset(ENUM {client,backend,session,thread})

Reset to the previous snapshot of a workspace, it must be the same workspace too.

workspace_overflowed

BOOL workspace_overflowed(ENUM {client,backend,session,thread})

Find whether the workspace overflow mark is set or not.

workspace_overflow

VOID workspace_overflow(ENUM {client,backend,session,thread})

Mark a workspace as overflowed.

typesize

INT typesize(STRING)

Returns the size in bytes of a collection of C-datatypes:

  • 'p': pointer

  • 'i': int

  • 'd': double

  • 'f': float

  • 'l': long

  • 's': short

  • 'z': size_t

  • 'o': off_t

  • 'j': intmax_t

This can be useful for VMOD authors in conjunction with workspace operations.

SEE ALSO