Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
VMOD_VTC(3)							   VMOD_VTC(3)

NAME
       vmod_vtc	- Utility module for varnishtest

SYNOPSIS
	  import vtc [as name] [from "path"]

	  VOID barrier_sync(STRING addr, DURATION timeout)

	  BACKEND no_backend()

	  STEVEDORE no_stevedore()

	  IP no_ip()

	  VOID panic(STRING)

	  VOID sleep(DURATION)

	  VOID workspace_alloc(ENUM, INT size)

	  BYTES	workspace_reserve(ENUM,	INT size)

	  INT workspace_free(ENUM)

	  VOID workspace_snapshot(ENUM)

	  VOID workspace_reset(ENUM)

	  BOOL workspace_overflowed(ENUM)

	  VOID workspace_overflow(ENUM)

	  BLOB workspace_dump(ENUM, ENUM, BYTES	off, BYTES len)

	  INT typesize(STRING)

	  BLOB proxy_header(ENUM version, IP client, IP	server,	STRING authority)

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.

   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  bar-
       rier  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
   BACKEND no_backend()
       Fails at	backend	selection.

   STEVEDORE no_stevedore()
       Fails at	storage	selection.

   IP no_ip()
       Returns a null IP address, not even a bogo_ip.

   VOID	panic(STRING)
       It can be useful	to crash the child process in order to	test  the  ro-
       bustness	of a VMOD.

   VOID	sleep(DURATION)
       Block the current worker	thread.

WORKSPACES
       It  can be useful to put	a workspace in a given state when testing cor-
       ner 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.

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

       Allocate	and zero out memory from a workspace. A	negative size will al-
       locate as much as needed	to leave that many bytes free. The actual  al-
       location	 size  may  be higher to comply	with memory alignment require-
       ments of	the CPU	architecture. A	failed allocation fails	 the  transac-
       tion.

   BYTES workspace_reserve(ENUM, INT size)
	  BYTES	workspace_reserve(
	     ENUM {client, backend, session, thread},
	     INT size
	  )

       Attempt	to  reserve size bytes and release the reservation right away.
       Return the size of the reservation.

       See vtc.workspace_alloc() for semantics of the size argument.

   INT workspace_free(ENUM {client, backend, session, thread})
       Find how	much unallocated space there is	left in	a workspace.

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

       Snapshot	a workspace. Only one snapshot may be active  at  a  time  and
       each  VCL  can  save  only  one snapshot, so concurrent tasks requiring
       snapshots are not supported.

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

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

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

       Find whether the	workspace overflow mark	is set or not.

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

       Mark a workspace	as overflowed.

   BLOB	workspace_dump(ENUM, ENUM, BYTES off, BYTES len)
	  BLOB workspace_dump(
	     ENUM {client, backend, session, thread},
	     ENUM {s, f, r},
	     BYTES off=0,
	     BYTES len=64
	  )

       Return  data  from  a workspace's s, f, or r pointer as a blob. Data is
       copied onto the primary workspace to avoid it being subsequently	 over-
       written.

       The maximum len is 1KB.

   INT typesize(STRING)
       Returns the size	in bytes of a collection of C-datatypes:

       o 'p': pointer

       o 'i': int

       o 'd': double

       o 'f': float

       o 'l': long

       o 's': short

       o 'z': size_t

       o 'o': off_t

       o 'j': intmax_t

       This can	be useful for VMOD authors in conjunction with workspace oper-
       ations.

   BLOB	proxy_header(ENUM version, IP client, IP server, STRING	authority)
	  BLOB proxy_header(
	     ENUM {v1, v2} version,
	     IP	client,
	     IP	server,
	     STRING authority=0
	  )

       Format a	proxy header of	the given version v1 or	v2 and addresses  (The
       VCL IP type also	conatins the port number).

       Optionally also send an authority TLV with version v2 (ignored for ver-
       sion v1).

       Candidate for moving into vmod_proxy, but there were concerns about the
       interface design

SEE ALSO
       o vtc(7)

       o vcl(7)

COPYRIGHT
	  Copyright (c)	2017 Varnish Software AS
	  All rights reserved.

	  Author: Dridi	Boukelmoune <dridi.boukelmoune@gmail.com>

	  SPDX-License-Identifier: BSD-2-Clause

	  Redistribution and use in source and binary forms, with or without
	  modification,	are permitted provided that the	following conditions
	  are met:
	  1. Redistributions of	source code must retain	the above copyright
	     notice, this list of conditions and the following disclaimer.
	  2. Redistributions in	binary form must reproduce the above copyright
	     notice, this list of conditions and the following disclaimer in the
	     documentation and/or other	materials provided with	the distribution.

	  THIS SOFTWARE	IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS	IS'' AND
	  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,	BUT NOT	LIMITED	TO, THE
	  IMPLIED WARRANTIES OF	MERCHANTABILITY	AND FITNESS FOR	A PARTICULAR PURPOSE
	  ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
	  FOR ANY DIRECT, INDIRECT, INCIDENTAL,	SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	  OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	  HOWEVER CAUSED AND ON	ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	  LIABILITY, OR	TORT (INCLUDING	NEGLIGENCE OR OTHERWISE) ARISING IN ANY	WAY
	  OUT OF THE USE OF THIS SOFTWARE, EVEN	IF ADVISED OF THE POSSIBILITY OF
	  SUCH DAMAGE.

								   VMOD_VTC(3)

NAME | SYNOPSIS | DESCRIPTION | MISCELLANEOUS | WORKSPACES | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=vmod_vtc&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help