vmod_globalvar(3)

Name
vmod_globalvar - global variables as objects for VCL

SYNOPSIS

            import globalvar [as name] [from "path"]

            new xacl = globalvar.acl([ACL init])

                ACL xacl.get([ACL fallback])

                VOID xacl.set(ACL)

                VOID xacl.undefine()

                BOOL xacl.defined()

            new xbackend = globalvar.backend([BACKEND init])

                BACKEND xbackend.get([BACKEND fallback])

                VOID xbackend.set(BACKEND)

                VOID xbackend.undefine()

                BOOL xbackend.defined()

            new xblob = globalvar.blob([BLOB init])

                BLOB xblob.get([BLOB fallback])

                VOID xblob.set(BLOB)

                VOID xblob.undefine()

                BOOL xblob.defined()

            new xbody = globalvar.body([BODY init])

                BODY xbody.get([BODY fallback])

                VOID xbody.set(BODY)

                VOID xbody.undefine()

                BOOL xbody.defined()

            new xbool = globalvar.bool([BOOL init])

                BOOL xbool.get([BOOL fallback])

                VOID xbool.set(BOOL)

                VOID xbool.undefine()

                BOOL xbool.defined()

            new xbytes = globalvar.bytes([BYTES init])

                BYTES xbytes.get([BYTES fallback])

                VOID xbytes.set(BYTES)

                VOID xbytes.undefine()

                BOOL xbytes.defined()

            new xduration = globalvar.duration([DURATION init])

                DURATION xduration.get([DURATION fallback])

                VOID xduration.set(DURATION)

                VOID xduration.undefine()

                BOOL xduration.defined()

            new xheader = globalvar.header([HEADER init])

                HEADER xheader.get([HEADER fallback])

                VOID xheader.set(HEADER)

                VOID xheader.undefine()

                BOOL xheader.defined()

            new xint = globalvar.int([INT init])

                INT xint.get([INT fallback])

                VOID xint.set(INT)

                VOID xint.undefine()

                BOOL xint.defined()

            new xip = globalvar.ip([IP init])

                IP xip.get([IP fallback])

                VOID xip.set(IP)

                VOID xip.undefine()

                BOOL xip.defined()

            new xprobe = globalvar.probe([PROBE init])

                PROBE xprobe.get([PROBE fallback])

                VOID xprobe.set(PROBE)

                VOID xprobe.undefine()

                BOOL xprobe.defined()

            new xreal = globalvar.real([REAL init])

                REAL xreal.get([REAL fallback])

                VOID xreal.set(REAL)

                VOID xreal.undefine()

                BOOL xreal.defined()

            new xstevedore = globalvar.stevedore([STEVEDORE init])

                STEVEDORE xstevedore.get([STEVEDORE fallback])

                VOID xstevedore.set(STEVEDORE)

                VOID xstevedore.undefine()

                BOOL xstevedore.defined()

            new xstring = globalvar.string([STRING init])

                STRING xstring.get([STRING fallback])

                VOID xstring.set(STRING)

                VOID xstring.undefine()

                BOOL xstring.defined()

            new xtime = globalvar.time([TIME init])

                TIME xtime.get([TIME fallback])

                VOID xtime.set(TIME)

                VOID xtime.undefine()

                BOOL xtime.defined()

DESCRIPTION

This module implements globally (per vcl) scoped variables as objects: All vcl subroutines have the same view on variables, any change comes in effect immediately.

The value of a globalvar is the either the initial value from the constructor or the last value assigned by any task executing the respective vcl.

If no value is set, it is undefined. A globalvar can also be undefined using the .undefine() method.

Attempts to .get() an undefined value will return the .get() method`s fallback argument. For most types, there is a default fallback; if there is none, using .get() on an undefined value triggers a VCL failure at runtime.

Where necessary, read access to globalvar variables is reference counted using priv_task state, such that changed variables` storage is not freed before the last access ceased.

Example with an initially undefined variable:

            import globalvar;

            sub vcl_init {
             new xint = globalvar.int();
            }

            sub vcl_recv {
             set req.http.def = xint.defined(); # false
             set req.http.fallback = xint.get(5); # 5
             xint.set(42);
            }

            \# in some other request, later

            sub vcl_deliver {
             set resp.http.the-answer = xint.get(); # 42
            }

The implementation of the various classes of this vmod is auto-generated, and so is the documentation. Thus, the documentation following this generic description is identical for all types except for the respective type names and the .get() fallback.

  new xacl = globalvar.acl([ACL init])

Construct a(n) ACL globalvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined.

  ACL xacl.get([ACL fallback])

Return the value of the globalvar or the fallback argument if it is undefined. Using .get() on an undefined value without a fallback triggers a VCL error.

  VOID xacl.set(ACL)

Set the value of the globalvar.

  VOID xacl.undefine()

Undefine the globalvar.

  BOOL xacl.defined()

Return whether the globalvar is defined.

  new xbackend = globalvar.backend([BACKEND init])

Construct a(n) BACKEND globalvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined.

  BACKEND xbackend.get([BACKEND fallback])

Return the value of the globalvar or the fallback argument if it is undefined. The default fallback is the None backend.

  VOID xbackend.set(BACKEND)

Set the value of the globalvar.

  VOID xbackend.undefine()

Undefine the globalvar.

  BOOL xbackend.defined()

Return whether the globalvar is defined.

  new xblob = globalvar.blob([BLOB init])

Construct a(n) BLOB globalvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined.

  BLOB xblob.get([BLOB fallback])

Return the value of the globalvar or the fallback argument if it is undefined. The default fallback is the null blob.

  VOID xblob.set(BLOB)

Set the value of the globalvar.

  VOID xblob.undefine()

Undefine the globalvar.

  BOOL xblob.defined()

Return whether the globalvar is defined.

  new xbody = globalvar.body([BODY init])

Construct a(n) BODY globalvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined.

  BODY xbody.get([BODY fallback])

Return the value of the globalvar or the fallback argument if it is undefined. Using .get() on an undefined value without a fallback triggers a VCL error.

  VOID xbody.set(BODY)

Set the value of the globalvar.

  VOID xbody.undefine()

Undefine the globalvar.

  BOOL xbody.defined()

Return whether the globalvar is defined.

  new xbool = globalvar.bool([BOOL init])

Construct a(n) BOOL globalvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined.

  BOOL xbool.get([BOOL fallback])

Return the value of the globalvar or the fallback argument if it is undefined. The default fallback is false

  VOID xbool.set(BOOL)

Set the value of the globalvar.

  VOID xbool.undefine()

Undefine the globalvar.

  BOOL xbool.defined()

Return whether the globalvar is defined.

  new xbytes = globalvar.bytes([BYTES init])

Construct a(n) BYTES globalvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined.

  BYTES xbytes.get([BYTES fallback])

Return the value of the globalvar or the fallback argument if it is undefined. The default fallback is 0 bytes.

  VOID xbytes.set(BYTES)

Set the value of the globalvar.

  VOID xbytes.undefine()

Undefine the globalvar.

  BOOL xbytes.defined()

Return whether the globalvar is defined.

  new xduration = globalvar.duration([DURATION init])

Construct a(n) DURATION globalvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined.

  DURATION xduration.get([DURATION fallback])

Return the value of the globalvar or the fallback argument if it is undefined. The default fallback is 0s.

  VOID xduration.set(DURATION)

Set the value of the globalvar.

  VOID xduration.undefine()

Undefine the globalvar.

  BOOL xduration.defined()

Return whether the globalvar is defined.

  new xheader = globalvar.header([HEADER init])

Construct a(n) HEADER globalvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined.

  HEADER xheader.get([HEADER fallback])

Return the value of the globalvar or the fallback argument if it is undefined. Using .get() on an undefined value without a fallback triggers a VCL error.

  VOID xheader.set(HEADER)

Set the value of the globalvar.

  VOID xheader.undefine()

Undefine the globalvar.

  BOOL xheader.defined()

Return whether the globalvar is defined.

  new xint = globalvar.int([INT init])

Construct a(n) INT globalvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined.

  INT xint.get([INT fallback])

Return the value of the globalvar or the fallback argument if it is undefined. The default fallback is 0.

  VOID xint.set(INT)

Set the value of the globalvar.

  VOID xint.undefine()

Undefine the globalvar.

  BOOL xint.defined()

Return whether the globalvar is defined.

  new xip = globalvar.ip([IP init])

Construct a(n) IP globalvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined.

  IP xip.get([IP fallback])

Return the value of the globalvar or the fallback argument if it is undefined. The default fallback is IPv4 0.0.0.0.

  VOID xip.set(IP)

Set the value of the globalvar.

  VOID xip.undefine()

Undefine the globalvar.

  BOOL xip.defined()

Return whether the globalvar is defined.

  new xprobe = globalvar.probe([PROBE init])

Construct a(n) PROBE globalvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined.

  PROBE xprobe.get([PROBE fallback])

Return the value of the globalvar or the fallback argument if it is undefined. The default fallback is no backend.

  VOID xprobe.set(PROBE)

Set the value of the globalvar.

  VOID xprobe.undefine()

Undefine the globalvar.

  BOOL xprobe.defined()

Return whether the globalvar is defined.

  new xreal = globalvar.real([REAL init])

Construct a(n) REAL globalvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined.

  REAL xreal.get([REAL fallback])

Return the value of the globalvar or the fallback argument if it is undefined. The default fallback is 0.0.

  VOID xreal.set(REAL)

Set the value of the globalvar.

  VOID xreal.undefine()

Undefine the globalvar.

  BOOL xreal.defined()

Return whether the globalvar is defined.

  new xstevedore = globalvar.stevedore([STEVEDORE init])

Construct a(n) STEVEDORE globalvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined.

  STEVEDORE xstevedore.get([STEVEDORE fallback])

Return the value of the globalvar or the fallback argument if it is undefined. The default fallback is the default storage.

  VOID xstevedore.set(STEVEDORE)

Set the value of the globalvar.

  VOID xstevedore.undefine()

Undefine the globalvar.

  BOOL xstevedore.defined()

Return whether the globalvar is defined.

  new xstring = globalvar.string([STRING init])

Construct a(n) STRING globalvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined.

  STRING xstring.get([STRING fallback])

Return the value of the globalvar or the fallback argument if it is undefined. The default fallback is the empty string.

  VOID xstring.set(STRING)

Set the value of the globalvar.

  VOID xstring.undefine()

Undefine the globalvar.

  BOOL xstring.defined()

Return whether the globalvar is defined.

  new xtime = globalvar.time([TIME init])

Construct a(n) TIME globalvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined.

  TIME xtime.get([TIME fallback])

Return the value of the globalvar or the fallback argument if it is undefined. The default fallback is the epoch (1970/1/1 0:00:00 GMT).

  VOID xtime.set(TIME)

Set the value of the globalvar.

  VOID xtime.undefine()

Undefine the globalvar.

  BOOL xtime.defined()

Return whether the globalvar is defined.

SEE ALSO

vcl(7),vinyld(1)

COPYRIGHT

            Copyright 2018-2022 UPLEX Nils Goroll Systemoptimierung

            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 COPYRIGHT HOLDERS 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 THE COPYRIGHT
            HOLDER 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.