1VMOD_VTC(3)                                                        VMOD_VTC(3)
2
3
4

NAME

6       vmod_vtc - Utility module for varnishtest
7

SYNOPSIS

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          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          INT typesize(STRING)
36

DESCRIPTION

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

MISCELLANEOUS

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

WORKSPACES

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

SEE ALSO

146       · vtc(7)
147
148       · vcl(7)
149

151          Copyright (c) 2017 Varnish Software AS
152          All rights reserved.
153
154          Author: Dridi Boukelmoune <dridi.boukelmoune@gmail.com>
155
156          Redistribution and use in source and binary forms, with or without
157          modification, are permitted provided that the following conditions
158          are met:
159          1. Redistributions of source code must retain the above copyright
160             notice, this list of conditions and the following disclaimer.
161          2. Redistributions in binary form must reproduce the above copyright
162             notice, this list of conditions and the following disclaimer in the
163             documentation and/or other materials provided with the distribution.
164
165          THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
166          ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
167          IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
168          ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
169          FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
170          DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
171          OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
172          HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
173          LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
174          OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
175          SUCH DAMAGE.
176
177
178
179
180                                                                   VMOD_VTC(3)
Impressum