1VMOD(VTC) VMOD(VTC)
2
6 VMOD vtc - Utility module for varnishtest
7
9 import vtc [as name] [from "path"]
10 VOID barrier_sync(STRING addr, DURATION timeout)
12 BACKEND no_backend()
14 STEVEDORE no_stevedore()
16 IP no_ip()
18 VOID panic(STRING)
20 VOID sleep(DURATION)
22 VOID workspace_alloc(ENUM, INT size)
24 BYTES workspace_reserve(ENUM, INT size)
26 INT workspace_free(ENUM)
28 VOID workspace_snapshot(ENUM)
30 VOID workspace_reset(ENUM)
32 BOOL workspace_overflowed(ENUM)
34 VOID workspace_overflow(ENUM)
36 BLOB workspace_dump(ENUM, ENUM, BYTES off, BYTES len)
38 INT typesize(STRING)
40
42 The goal for this VMOD is to provide VCL users and VMOD authors means
43 to test corner cases or reach certain conditions with varnishtest.
44 VOID barrier_sync(STRING addr, DURATION timeout=0)
46 When writing test cases, the most common pattern is to start a mock
47 server instance, a Varnish instance, and spin up a mock client. Those
48 entities run asynchronously, and others exist like background processes
49 (process) or log readers (logexpect). While you can synchronize with
50 individual entities and wait for their completion, you must use a bar‐
51 rier if you need to synchronize two or more entities, or wait until a
52 certain point instead of completion.
53 Not only is it possible to synchronize between test entities, with the
55 barrier_sync function you can even synchronize VCL code:
56 sub vcl_recv {
58 # wait for some barrier b1 to complete
59 vtc.barrier_sync("${b1_sock}");
60 }
61 If the function fails to synchronize with the barrier for some reason,
63 or if it reaches the optional timeout, it fails the VCL transaction.
64
66 BACKEND no_backend()
67 Fails at backend selection.
68 STEVEDORE no_stevedore()
70 Fails at storage selection.
71 IP no_ip()
73 Returns a null IP address, not even a bogo_ip.
74 VOID panic(STRING)
76 It can be useful to crash the child process in order to test the
77 robustness of a VMOD.
78 VOID sleep(DURATION)
80 Block the current worker thread.
81
83 It can be useful to put a workspace in a given state when testing cor‐
84 ner cases like resource exhaustion for a transaction, especially for
85 VMOD development. All functions available allow to pick which workspace
86 you need to tamper with, available values are client, backend, session
87 and thread.
88 VOID workspace_alloc(ENUM, INT size)
90 VOID workspace_alloc(
91 ENUM {client, backend, session, thread},
92 INT size
93 )
94 Allocate and zero out memory from a workspace. A negative size will
96 allocate as much as needed to leave that many bytes free. The actual
97 allocation size may be higher to comply with memory alignment require‐
98 ments of the CPU architecture. A failed allocation fails the transac‐
99 tion.
100 BYTES workspace_reserve(ENUM, INT size)
102 BYTES workspace_reserve(
103 ENUM {client, backend, session, thread},
104 INT size
105 )
106 Attempt to reserve size bytes and release the reservation right away.
108 Return the size of the reservation.
109 See vtc.workspace_alloc() for semantics of the size argument.
111 INT workspace_free(ENUM {client, backend, session, thread})
113 Find how much unallocated space there is left in a workspace.
114 VOID workspace_snapshot(ENUM)
116 VOID workspace_snapshot(ENUM {client, backend, session, thread})
117 Snapshot a workspace. Only one snapshot may be active at a time and
119 each VCL can save only one snapshot, so concurrent tasks requiring
120 snapshots are not supported.
121 VOID workspace_reset(ENUM)
123 VOID workspace_reset(ENUM {client, backend, session, thread})
124 Reset to the previous snapshot of a workspace, it must be the same
126 workspace too.
127 BOOL workspace_overflowed(ENUM)
129 BOOL workspace_overflowed(ENUM {client, backend, session, thread})
130 Find whether the workspace overflow mark is set or not.
132 VOID workspace_overflow(ENUM)
134 VOID workspace_overflow(ENUM {client, backend, session, thread})
135 Mark a workspace as overflowed.
137 BLOB workspace_dump(ENUM, ENUM, BYTES off, BYTES len)
139 BLOB workspace_dump(
140 ENUM {client, backend, session, thread},
141 ENUM {s, f, r},
142 BYTES off=0,
143 BYTES len=64
144 )
145 Return data from a workspace's s, f, or r pointer as a blob. Data is
147 copied onto the primary workspace to avoid it being subsequently over‐
148 written.
149 The maximum len is 1KB.
151 INT typesize(STRING)
153 Returns the size in bytes of a collection of C-datatypes:
154 · 'p': pointer
156 · 'i': int
158 · 'd': double
160 · 'f': float
162 · 'l': long
164 · 's': short
166 · 'z': size_t
168 · 'o': off_t
170 · 'j': intmax_t
172 This can be useful for VMOD authors in conjunction with workspace oper‐
174 ations.
175
177 · vtc(7)
178 · vcl(7)
180
182 Copyright (c) 2017 Varnish Software AS
183 All rights reserved.
184 Author: Dridi Boukelmoune <dridi.boukelmoune@gmail.com>
186 Redistribution and use in source and binary forms, with or without
188 modification, are permitted provided that the following conditions
189 are met:
190 1. Redistributions of source code must retain the above copyright
191 notice, this list of conditions and the following disclaimer.
192 2. Redistributions in binary form must reproduce the above copyright
193 notice, this list of conditions and the following disclaimer in the
194 documentation and/or other materials provided with the distribution.
195 THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
197 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
198 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
199 ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
200 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
201 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
202 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
203 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
204 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
205 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
206 SUCH DAMAGE.
207 3 VMOD(VTC)