1VMOD_VTC(3) VMOD_VTC(3)
2
3
4
6 vmod_vtc - Utility module for varnishtest
7
9 import vtc [from "path"] ;
10
11 VOID barrier_sync(STRING addr, DURATION timeout)
12
13 BACKEND no_backend()
14
15 STEVEDORE no_stevedore()
16
17 VOID panic(STRING)
18
19 VOID sleep(DURATION)
20
21 VOID workspace_alloc(ENUM, INT size)
22
23 INT workspace_free(ENUM)
24
25 VOID workspace_snapshot(ENUM)
26
27 VOID workspace_reset(ENUM)
28
29 BOOL workspace_overflowed(ENUM)
30
31 VOID workspace_overflow(ENUM)
32
33 INT typesize(STRING)
34
36 The goal for this VMOD is to provide VCL users and VMOD authors means
37 to test corner cases or reach certain conditions with varnishtest.
38
39 VOID barrier_sync(STRING addr, DURATION timeout=0)
40 When writing test cases, the most common pattern is to start a mock
41 server instance, a Varnish instance, and spin up a mock client. Those
42 entities run asynchronously, and others exist like background processes
43 (process) or log readers (logexpect). While you can synchronize with
44 individual entities and wait for their completion, you must use a bar‐
45 rier if you need to synchronize two or more entities, or wait until a
46 certain point instead of completion.
47
48 Not only is it possible to synchronize between test entities, with the
49 barrier_sync function you can even synchronize VCL code:
50
51 sub vcl_recv {
52 # wait for some barrier b1 to complete
53 vtc.barrier_sync("${b1_sock}");
54 }
55
56 If the function fails to synchronize with the barrier for some reason,
57 or if it reaches the optional timeout, it fails the VCL transaction.
58
60 BACKEND no_backend()
61 Fails at backend selection.
62
63 STEVEDORE no_stevedore()
64 Fails at storage selection.
65
66 VOID panic(STRING)
67 It can be useful to crash the child process in order to test the
68 robustness of a VMOD.
69
70 VOID sleep(DURATION)
71 Block the current worker thread.
72
74 It can be useful to put a workspace in a given state when testing cor‐
75 ner cases like resource exhaustion for a transaction, especially for
76 VMOD development. All functions available allow to pick which workspace
77 you need to tamper with, available values are client, backend, session
78 and thread.
79
80 VOID workspace_alloc(ENUM, INT size)
81 VOID workspace_alloc(
82 ENUM {client, backend, session, thread},
83 INT size
84 )
85
86 Allocate and zero out memory from a workspace. A negative size will
87 allocate as much as needed to leave that many bytes free. The actual
88 allocation size may be higher to comply with memory alignment require‐
89 ments of the CPU architecture. A failed allocation fails the transac‐
90 tion.
91
92 INT workspace_free(ENUM {client, backend, session, thread})
93 Find how much unallocated space there is left in a workspace.
94
95 VOID workspace_snapshot(ENUM)
96 VOID workspace_snapshot(ENUM {client, backend, session, thread})
97
98 Snapshot a workspace. Only one snapshot may be active at a time.
99
100 VOID workspace_reset(ENUM)
101 VOID workspace_reset(ENUM {client, backend, session, thread})
102
103 Reset to the previous snapshot of a workspace, it must be the same
104 workspace too.
105
106 BOOL workspace_overflowed(ENUM)
107 BOOL workspace_overflowed(ENUM {client, backend, session, thread})
108
109 Find whether the workspace overflow mark is set or not.
110
111 VOID workspace_overflow(ENUM)
112 VOID workspace_overflow(ENUM {client, backend, session, thread})
113
114 Mark a workspace as overflowed.
115
116 INT typesize(STRING)
117 Returns the size in bytes of a collection of C-datatypes:
118
119 · 'p': pointer
120
121 · 'i': int
122
123 · 'd': double
124
125 · 'f': float
126
127 · 'l': long
128
129 · 's': short
130
131 · 'z': size_t
132
133 · 'o': off_t
134
135 · 'j': intmax_t
136
137 This can be useful for VMOD authors in conjunction with workspace oper‐
138 ations.
139
141 · vtc(7)
142
143 · vcl(7)
144
146 Copyright (c) 2017 Varnish Software AS
147 All rights reserved.
148
149 Author: Dridi Boukelmoune <dridi.boukelmoune@gmail.com>
150
151 Redistribution and use in source and binary forms, with or without
152 modification, are permitted provided that the following conditions
153 are met:
154 1. Redistributions of source code must retain the above copyright
155 notice, this list of conditions and the following disclaimer.
156 2. Redistributions in binary form must reproduce the above copyright
157 notice, this list of conditions and the following disclaimer in the
158 documentation and/or other materials provided with the distribution.
159
160 THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
161 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
162 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
163 ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
164 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
165 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
166 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
167 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
168 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
169 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
170 SUCH DAMAGE.
171
172
173
174
175 VMOD_VTC(3)