1VMOD(VTC)                                                            VMOD(VTC)
2
3
4

NAME

6       VMOD vtc - Utility module for varnishtest
7

SYNOPSIS

9          import vtc [as name] [from "path"]
10
11          VOID barrier_sync(STRING addr, DURATION timeout)
12
13          BACKEND no_backend()
14
15          STEVEDORE no_stevedore()
16
17          IP no_ip()
18
19          VOID panic(STRING)
20
21          VOID sleep(DURATION)
22
23          VOID workspace_alloc(ENUM, INT size)
24
25          INT workspace_free(ENUM)
26
27          VOID workspace_snapshot(ENUM)
28
29          VOID workspace_reset(ENUM)
30
31          BOOL workspace_overflowed(ENUM)
32
33          VOID workspace_overflow(ENUM)
34
35          BLOB workspace_dump(ENUM, ENUM, BYTES off, BYTES len)
36
37          INT typesize(STRING)
38

DESCRIPTION

40       The  goal  for this VMOD is to provide VCL users and VMOD authors means
41       to test corner cases or reach certain conditions with varnishtest.
42
43   VOID barrier_sync(STRING addr, DURATION timeout=0)
44       When writing test cases, the most common pattern is  to  start  a  mock
45       server  instance,  a Varnish instance, and spin up a mock client. Those
46       entities run asynchronously, and others exist like background processes
47       (process)  or  log  readers (logexpect). While you can synchronize with
48       individual entities and wait for their completion, you must use a  bar‐
49       rier  if  you need to synchronize two or more entities, or wait until a
50       certain point instead of completion.
51
52       Not only is it possible to synchronize between test entities, with  the
53       barrier_sync function you can even synchronize VCL code:
54
55          sub vcl_recv {
56              # wait for some barrier b1 to complete
57              vtc.barrier_sync("${b1_sock}");
58          }
59
60       If  the function fails to synchronize with the barrier for some reason,
61       or if it reaches the optional timeout, it fails the VCL transaction.
62

MISCELLANEOUS

64   BACKEND no_backend()
65       Fails at backend selection.
66
67   STEVEDORE no_stevedore()
68       Fails at storage selection.
69
70   IP no_ip()
71       Returns a null IP address, not even a bogo_ip.
72
73   VOID panic(STRING)
74       It can be useful to crash the  child  process  in  order  to  test  the
75       robustness of a VMOD.
76
77   VOID sleep(DURATION)
78       Block the current worker thread.
79

WORKSPACES

81       It  can be useful to put a workspace in a given state when testing cor‐
82       ner cases like resource exhaustion for a  transaction,  especially  for
83       VMOD development. All functions available allow to pick which workspace
84       you need to tamper with, available values are client, backend,  session
85       and thread.
86
87   VOID workspace_alloc(ENUM, INT size)
88          VOID workspace_alloc(
89             ENUM {client, backend, session, thread},
90             INT size
91          )
92
93       Allocate  and  zero  out  memory from a workspace. A negative size will
94       allocate as much as needed to leave that many bytes  free.  The  actual
95       allocation  size may be higher to comply with memory alignment require‐
96       ments of the CPU architecture. A failed allocation fails  the  transac‐
97       tion.
98
99   INT workspace_free(ENUM {client, backend, session, thread})
100       Find how much unallocated space there is left in a workspace.
101
102   VOID workspace_snapshot(ENUM)
103          VOID workspace_snapshot(ENUM {client, backend, session, thread})
104
105       Snapshot  a  workspace.  Only  one snapshot may be active at a time and
106       each VCL can save only one  snapshot,  so  concurrent  tasks  requiring
107       snapshots are not supported.
108
109   VOID workspace_reset(ENUM)
110          VOID workspace_reset(ENUM {client, backend, session, thread})
111
112       Reset  to  the  previous  snapshot  of a workspace, it must be the same
113       workspace too.
114
115   BOOL workspace_overflowed(ENUM)
116          BOOL workspace_overflowed(ENUM {client, backend, session, thread})
117
118       Find whether the workspace overflow mark is set or not.
119
120   VOID workspace_overflow(ENUM)
121          VOID workspace_overflow(ENUM {client, backend, session, thread})
122
123       Mark a workspace as overflowed.
124
125   BLOB workspace_dump(ENUM, ENUM, BYTES off, BYTES len)
126          BLOB workspace_dump(
127             ENUM {client, backend, session, thread},
128             ENUM {s, f, r},
129             BYTES off=0,
130             BYTES len=64
131          )
132
133       Return data from a workspace's s, f, or r pointer as a  blob.  Data  is
134       copied  onto the primary workspace to avoid it being subsequently over‐
135       written.
136
137       The maximum len is 1KB.
138
139   INT typesize(STRING)
140       Returns the size in bytes of a collection of C-datatypes:
141
142       · 'p': pointer
143
144       · 'i': int
145
146       · 'd': double
147
148       · 'f': float
149
150       · 'l': long
151
152       · 's': short
153
154       · 'z': size_t
155
156       · 'o': off_t
157
158       · 'j': intmax_t
159
160       This can be useful for VMOD authors in conjunction with workspace oper‐
161       ations.
162

SEE ALSO

164       · vtc(7)
165
166       · vcl(7)
167
169          Copyright (c) 2017 Varnish Software AS
170          All rights reserved.
171
172          Author: Dridi Boukelmoune <dridi.boukelmoune@gmail.com>
173
174          Redistribution and use in source and binary forms, with or without
175          modification, are permitted provided that the following conditions
176          are met:
177          1. Redistributions of source code must retain the above copyright
178             notice, this list of conditions and the following disclaimer.
179          2. Redistributions in binary form must reproduce the above copyright
180             notice, this list of conditions and the following disclaimer in the
181             documentation and/or other materials provided with the distribution.
182
183          THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
184          ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
185          IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
186          ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
187          FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
188          DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
189          OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
190          HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
191          LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
192          OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
193          SUCH DAMAGE.
194
195
196
197
198                                       3                             VMOD(VTC)
Impressum