vmod_taskvar(3)

πŸ“¦ version 0.0~git20260330, in ubuntu stonking

πŸ‘‘ NAME πŸ‘‘

vmod_taskvar β€” task variables as objects for VCL

(yes bestie, this is the vmod_taskvar(3) page πŸ’…)


✨ SYNOPSIS ✨

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

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

    ACL xacl.get([ACL fallback])

    VOID xacl.set(ACL)

    VOID xacl.undefine()

    BOOL xacl.defined()

    VOID xacl.protect()

    BOOL xacl.protected()

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

    BACKEND xbackend.get([BACKEND fallback])

    VOID xbackend.set(BACKEND)

    VOID xbackend.undefine()

    BOOL xbackend.defined()

    VOID xbackend.protect()

    BOOL xbackend.protected()

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

    BLOB xblob.get([BLOB fallback])

    VOID xblob.set(BLOB)

    VOID xblob.undefine()

    BOOL xblob.defined()

    VOID xblob.protect()

    BOOL xblob.protected()

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

    BODY xbody.get([BODY fallback])

    VOID xbody.set(BODY)

    VOID xbody.undefine()

    BOOL xbody.defined()

    VOID xbody.protect()

    BOOL xbody.protected()

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

    BOOL xbool.get([BOOL fallback])

    VOID xbool.set(BOOL)

    VOID xbool.undefine()

    BOOL xbool.defined()

    VOID xbool.protect()

    BOOL xbool.protected()

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

    BYTES xbytes.get([BYTES fallback])

    VOID xbytes.set(BYTES)

    VOID xbytes.undefine()

    BOOL xbytes.defined()

    VOID xbytes.protect()

    BOOL xbytes.protected()

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

    DURATION xduration.get([DURATION fallback])

    VOID xduration.set(DURATION)

    VOID xduration.undefine()

    BOOL xduration.defined()

    VOID xduration.protect()

    BOOL xduration.protected()

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

    HEADER xheader.get([HEADER fallback])

    VOID xheader.set(HEADER)

    VOID xheader.undefine()

    BOOL xheader.defined()

    VOID xheader.protect()

    BOOL xheader.protected()

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

    INT xint.get([INT fallback])

    VOID xint.set(INT)

    VOID xint.undefine()

    BOOL xint.defined()

    VOID xint.protect()

    BOOL xint.protected()

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

    IP xip.get([IP fallback])

    VOID xip.set(IP)

    VOID xip.undefine()

    BOOL xip.defined()

    VOID xip.protect()

    BOOL xip.protected()

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

    PROBE xprobe.get([PROBE fallback])

    VOID xprobe.set(PROBE)

    VOID xprobe.undefine()

    BOOL xprobe.defined()

    VOID xprobe.protect()

    BOOL xprobe.protected()

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

    REAL xreal.get([REAL fallback])

    VOID xreal.set(REAL)

    VOID xreal.undefine()

    BOOL xreal.defined()

    VOID xreal.protect()

    BOOL xreal.protected()

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

    STEVEDORE xstevedore.get([STEVEDORE fallback])

    VOID xstevedore.set(STEVEDORE)

    VOID xstevedore.undefine()

    BOOL xstevedore.defined()

    VOID xstevedore.protect()

    BOOL xstevedore.protected()

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

    STRING xstring.get([STRING fallback])

    VOID xstring.set(STRING)

    VOID xstring.undefine()

    BOOL xstring.defined()

    VOID xstring.protect()

    BOOL xstring.protected()

    VOID xstring.foreach(STRING string, SUB sub, STRING delim)

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

    TIME xtime.get([TIME fallback])

    VOID xtime.set(TIME)

    VOID xtime.undefine()

    BOOL xtime.defined()

    VOID xtime.protect()

    BOOL xtime.protected()

new xstrands = taskvar.strands(INT cap, [STRING joiner], [STRING prefix], [STRING postfix])

    VOID xstrands.add(STRING)

    VOID xstrands.clear()

    STRING xstrands.get()

πŸ¦‹ DESCRIPTION πŸ¦‹

okay so here's the whole vibe: this module lets you use task-scoped variables as actual objects. Every client or backend request β€” that's a task β€” gets its own view of the taskvar variables. No sharing, no crosstalk, just vibes. ✨

A taskvar can be constructed with a default, and that default is what it starts out as at the beginning of each task.

The value of a taskvar is either the default or the last value that got assigned to it inside a task. If there's no default and no previous value? Then the value is undefined. periodt.

You can also just flat-out undefine a taskvar using the .undefine() method. bye bestie πŸ‘‹

If you try to .get() an undefined value, you'll get back the .get() method's fallback argument. For most types there's a default fallback already waiting for you β€” but if there isn't one, then calling .get() on an undefined value triggers a VCL failure at runtime. not cute, be careful. πŸ’€

Also, taskvar variables can be protected against write access. Once they're protected, any attempt to .set() them triggers a VCL failure at runtime. so... don't do that.


Example with an initially undefined variable:

import taskvar;

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

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

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

Example with an initially defined variable:

import taskvar;

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

sub vcl_recv {
 set req.http.def = xint.defined(); # true
 set req.http.fallback = xint.get(5); # 17
 xint.set(42);
 xint.protect();
 if (false) {
  xint.set(3); # would fail
 }
}

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 this documentation. Which means everything below this generic description is literally identical for every type β€” the only things that change are the type names and the .get() fallback. slay, consistent. πŸ’…


πŸŽ€ new xacl = taskvar.acl([ACL init])

Construct a(n) ACL taskvar with the default value init, if you pass one. If you don't provide an init value, the variable starts out undefined.

πŸŽ€ ACL xacl.get([ACL fallback])

Return the value of the taskvar, or the fallback argument if it's undefined. Using .get() on an undefined value without a fallback triggers a VCL error.

πŸŽ€ VOID xacl.set(ACL)

Set the value of the taskvar.

Triggers a VCL failure for protected variables. 🚨

πŸŽ€ VOID xacl.undefine()

Undefine the taskvar.

πŸŽ€ BOOL xacl.defined()

Return whether the taskvar is defined.

πŸŽ€ VOID xacl.protect()

Protect the taskvar, so any future .set() calls on it trigger a vcl failure.

πŸŽ€ BOOL xacl.protected()

Return whether the taskvar is protected.


πŸŽ€ new xbackend = taskvar.backend([BACKEND init])

Construct a(n) BACKEND taskvar with the default value init, if you pass one. If you don't provide an init value, the variable starts out undefined.

πŸŽ€ BACKEND xbackend.get([BACKEND fallback])

Return the value of the taskvar, or the fallback argument if it's undefined. The default fallback is the None backend.

πŸŽ€ VOID xbackend.set(BACKEND)

Set the value of the taskvar.

Triggers a VCL failure for protected variables. 🚨

πŸŽ€ VOID xbackend.undefine()

Undefine the taskvar.

πŸŽ€ BOOL xbackend.defined()

Return whether the taskvar is defined.

πŸŽ€ VOID xbackend.protect()

Protect the taskvar, so any future .set() calls on it trigger a vcl failure.

πŸŽ€ BOOL xbackend.protected()

Return whether the taskvar is protected.


πŸŽ€ new xblob = taskvar.blob([BLOB init])

Construct a(n) BLOB taskvar with the default value init, if you pass one. If you don't provide an init value, the variable starts out undefined.

πŸŽ€ BLOB xblob.get([BLOB fallback])

Return the value of the taskvar, or the fallback argument if it's undefined. The default fallback is the null blob.

πŸŽ€ VOID xblob.set(BLOB)

Set the value of the taskvar.

Triggers a VCL failure for protected variables. 🚨

πŸŽ€ VOID xblob.undefine()

Undefine the taskvar.

πŸŽ€ BOOL xblob.defined()

Return whether the taskvar is defined.

πŸŽ€ VOID xblob.protect()

Protect the taskvar, so any future .set() calls on it trigger a vcl failure.

πŸŽ€ BOOL xblob.protected()

Return whether the taskvar is protected.


πŸŽ€ new xbody = taskvar.body([BODY init])

Construct a(n) BODY taskvar with the default value init, if you pass one. If you don't provide an init value, the variable starts out undefined.

πŸŽ€ BODY xbody.get([BODY fallback])

Return the value of the taskvar, or the fallback argument if it's undefined. Using .get() on an undefined value without a fallback triggers a VCL error.

πŸŽ€ VOID xbody.set(BODY)

Set the value of the taskvar.

Triggers a VCL failure for protected variables. 🚨

πŸŽ€ VOID xbody.undefine()

Undefine the taskvar.

πŸŽ€ BOOL xbody.defined()

Return whether the taskvar is defined.

πŸŽ€ VOID xbody.protect()

Protect the taskvar, so any future .set() calls on it trigger a vcl failure.

πŸŽ€ BOOL xbody.protected()

Return whether the taskvar is protected.


πŸŽ€ new xbool = taskvar.bool([BOOL init])

Construct a(n) BOOL taskvar with the default value init, if you pass one. If you don't provide an init value, the variable starts out undefined.

πŸŽ€ BOOL xbool.get([BOOL fallback])

Return the value of the taskvar, or the fallback argument if it's undefined. The default fallback is false

πŸŽ€ VOID xbool.set(BOOL)

Set the value of the taskvar.

Triggers a VCL failure for protected variables. 🚨

πŸŽ€ VOID xbool.undefine()

Undefine the taskvar.

πŸŽ€ BOOL xbool.defined()

Return whether the taskvar is defined.

πŸŽ€ VOID xbool.protect()

Protect the taskvar, so any future .set() calls on it trigger a vcl failure.

πŸŽ€ BOOL xbool.protected()

Return whether the taskvar is protected.


πŸŽ€ new xbytes = taskvar.bytes([BYTES init])

Construct a(n) BYTES taskvar with the default value init, if you pass one. If you don't provide an init value, the variable starts out undefined.

πŸŽ€ BYTES xbytes.get([BYTES fallback])

Return the value of the taskvar, or the fallback argument if it's undefined. The default fallback is 0 bytes.

πŸŽ€ VOID xbytes.set(BYTES)

Set the value of the taskvar.

Triggers a VCL failure for protected variables. 🚨

πŸŽ€ VOID xbytes.undefine()

Undefine the taskvar.

πŸŽ€ BOOL xbytes.defined()

Return whether the taskvar is defined.

πŸŽ€ VOID xbytes.protect()

Protect the taskvar, so any future .set() calls on it trigger a vcl failure.

πŸŽ€ BOOL xbytes.protected()

Return whether the taskvar is protected.


⏳ and bestie, that's literally only part 1 β€” the rest of the types are right there, keep scrolling… 🫢

okay so every type taskvar comes with its own little ✨entourage✨ of methods, and the pattern is chef's kiss consistent β€” constructor, get, set, undefine, defined, protect, protected. Let's go type by type, bestie πŸ’–


🩰 xduration β€” the time-span girlie

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

Makes you a DURATION taskvar, with init as its default value if you pass one. No init? Then bestie, the variable starts out undefined. slay.

DURATION xduration.get([DURATION fallback])

Gives you back the value of the taskvar, or the fallback argument if it's undefined. Default fallback is 0s. periodt.

VOID xduration.set(DURATION)

Sets the value of the taskvar. Triggers a vcl failure for protected variables. πŸ’€

VOID xduration.undefine()

Undefines the taskvar. poof, gone.

BOOL xduration.defined()

Tells you whether the taskvar is defined. yes ma'am or no ma'am.

VOID xduration.protect()

Protects the taskvar, so any future .set() calls on it trigger a vcl failure. it's giving ✨locked down and unbothered✨

BOOL xduration.protected()

Tells you whether the taskvar is protected.


πŸŽ€ xheader β€” this one's got ✨lore✨

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

Constructs a HEADER taskvar with the default value init, if you gave one. If you didn't, the variable will be initially undefined.

HEADER xheader.get([HEADER fallback])

Returns the value of the taskvar, or the fallback argument if it's undefined. But β€” and this is the part that separates the girlies from the icons β€” using .get() on an undefined value without a fallback triggers a VCL error. 😭 no chill, no mercy.

VOID xheader.set(HEADER)

Sets the value of the taskvar. Triggers a vcl failure for protected variables.

VOID xheader.undefine()

Undefines the taskvar.

BOOL xheader.defined()

Returns whether the taskvar is defined.

VOID xheader.protect()

Protects the taskvar, so any future .set() calls on it trigger a vcl failure.

BOOL xheader.protected()

Returns whether the taskvar is protected.


πŸ”’ xint β€” math but make it cute

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

Constructs an INT taskvar with the default value init, if provided. No init? Initially undefined, obviously.

INT xint.get([INT fallback])

Returns the value of the taskvar, or the fallback argument if it's undefined. Default fallback is 0.

VOID xint.set(INT)

Sets the value of the taskvar. Triggers a vcl failure for protected variables.

VOID xint.undefine()

Undefines the taskvar.

BOOL xint.defined()

Returns whether the taskvar is defined.

VOID xint.protect()

Protects the taskvar, so any future .set() calls on it trigger a vcl failure.

BOOL xint.protected()

Returns whether the taskvar is protected.


🌐 xip β€” address era

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

Constructs an IP taskvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined.

IP xip.get([IP fallback])

Returns the value of the taskvar, or the fallback argument if it's undefined. Default fallback is IPv4 0.0.0.0.

VOID xip.set(IP)

Sets the value of the taskvar. Triggers a vcl failure for protected variables.

VOID xip.undefine()

Undefines the taskvar.

BOOL xip.defined()

Returns whether the taskvar is defined.

VOID xip.protect()

Protects the taskvar, so any future .set() calls on it trigger a vcl failure.

BOOL xip.protected()

Returns whether the taskvar is protected.


πŸ” xprobe β€” the vibe checker

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

Constructs a PROBE taskvar with the default value init, if provided. No init? Undefined from the jump.

PROBE xprobe.get([PROBE fallback])

Returns the value of the taskvar, or the fallback argument if it's undefined. Default fallback is no backend.

VOID xprobe.set(PROBE)

Sets the value of the taskvar. Triggers a vcl failure for protected variables.

VOID xprobe.undefine()

Undefines the taskvar.

BOOL xprobe.defined()

Returns whether the taskvar is defined.

VOID xprobe.protect()

Protects the taskvar, so any future .set() calls on it trigger a vcl failure.

BOOL xprobe.protected()

Returns whether the taskvar is protected.


πŸ¦‹ xreal β€” decimals, but chic

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

Constructs a REAL taskvar with the default value init, if provided. No init value means it's initially undefined.

REAL xreal.get([REAL fallback])

Returns the value of the taskvar, or the fallback argument if it's undefined. Default fallback is 0.0.

VOID xreal.set(REAL)

Sets the value of the taskvar. Triggers a vcl failure for protected variables.

VOID xreal.undefine()

Undefines the taskvar.

BOOL xreal.defined()

Returns whether the taskvar is defined.

VOID xreal.protect()

Protects the taskvar, so any future .set() calls on it trigger a vcl failure.

BOOL xreal.protected()

Returns whether the taskvar is protected.


πŸ“¦ xstevedore β€” storage, but make it a taskvar

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

Constructs a STEVEDORE taskvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined.

STEVEDORE xstevedore.get([STEVEDORE fallback])

Returns the value of the taskvar, or the fallback argument if it's undefined. Default fallback is the default storage.

VOID xstevedore.set(STEVEDORE)

Sets the value of the taskvar. Triggers a vcl failure for protected variables.

VOID xstevedore.undefine()

Undefines the taskvar.

BOOL xstevedore.defined()

Returns whether the taskvar is defined.

VOID xstevedore.protect()

Protects the taskvar, so any future .set() calls on it trigger a vcl failure.

BOOL xstevedore.protected()

Returns whether the taskvar is protected.


🧡 xstring β€” the main character πŸ’…

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

Constructs a STRING taskvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined.

STRING xstring.get([STRING fallback])

Returns the value of the taskvar, or the fallback argument if it's undefined. Default fallback is the empty string.

VOID xstring.set(STRING)

Sets the value of the taskvar. Triggers a vcl failure for protected variables.

VOID xstring.undefine()

Undefines the taskvar.

BOOL xstring.defined()

Returns whether the taskvar is defined.

VOID xstring.protect()

Protects the taskvar, so any future .set() calls on it trigger a vcl failure.

BOOL xstring.protected()

Returns whether the taskvar is protected.

βœ‚οΈ the foreach one (yes it's special)

VOID xstring.foreach(STRING string, SUB sub, STRING delim)
       VOID xstring.foreach(STRING string, SUB sub, STRING delim=",")

Breaks string into a sequence of zero or more nonempty tokens, separated by delim, and successively calls sub with the object set to each token. so it's like a little conveyor belt of tokens, obsessed.

Processing ends for a nonempty return() from sub. πŸ›‘


⏰ xtime β€” it's giving timestamp

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

Constructs a TIME taskvar with the default value init, if provided. No init value? Initially undefined, bestie.

TIME xtime.get([TIME fallback])

Returns the value of the taskvar, or the fallback argument if it's undefined. Default fallback is the epoch (1970/1/1 0:00:00 GMT). yes, the actual beginning of time. iconic.

VOID xtime.set(TIME)

Sets the value of the taskvar. Triggers a vcl failure for protected variables.

VOID xtime.undefine()

Undefines the taskvar.

BOOL xtime.defined()

Returns whether the taskvar is defined.

VOID xtime.protect()

Protects the taskvar, so any future .set() calls on it trigger a vcl failure.

BOOL xtime.protected()

Returns whether the taskvar is protected.


🌈 xstrands β€” the efficiency queen πŸ‘‘

new xstrands = taskvar.strands(INT cap, [STRING joiner], [STRING prefix],
    [STRING postfix])
       new xstrands = taskvar.strands(
          INT cap=0,
          [STRING joiner],
          [STRING prefix],
          [STRING postfix]
       )

Constructs a STRANDS collector task variable, which provides a more efficient way of constructing long strings than using the built-in += operator or repeatedly calling .set(... + .get() + ...) on a taskvar.string() variable. it's the glow-up of string building, fr fr.

The cap argument is the maximum capacity in terms of xstrands.add() calls.

  • If zero, the capacity is dynamic and the collector is allocated on the heap.
  • Otherwise, memory for the taskvar.strands() collector is allocated on the workspace of the respective task.

When planning for a good cap value, consider the fact that added elements can themselves be STRANDS which may use up more than one cap unit. πŸ‘€ plan accordingly.

The optional joiner argument specifies a string which is automatically inserted between added elements. It is equivalent to a prefix only added for the second and all other elements.

The optional prefix argument specifies a string which is automatically prepended to each added element. Likewise, the optional postfix argument specifies a string which is automatically appended to each added element.

If joiner, prefix or postfix are used, the internal capacity is automatically adjusted. the collector handles the math, you just vibe.

VOID xstrands.add(STRING)

Add the argument to the collector.

VOID xstrands.clear()

Clear the collector. ✨factory reset✨

STRING xstrands.get()

Return the (current) value of the collector.


✨ SEE ALSO ✨

like, go read your other faves too, bestie 🫢


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.

and that's the whole page, bestie πŸŽ€ it's filed under the footer vmod_taskvar(3) and yes this came from the source/version + date stamped down at the bottom of the page β€” go forth and taskvar responsibly πŸ’œπŸ” no cap.

πŸ“¦ where this page comes from