[master] 57336bb12 have a go at some vmod objects dev doc (not new for 6.1)
Nils Goroll
nils.goroll at uplex.de
Wed Sep 12 08:24:13 UTC 2018
commit 57336bb12a702c23f723b11a63e09e1eb80994d4
Author: Nils Goroll <nils.goroll at uplex.de>
Date: Wed Sep 12 10:22:51 2018 +0200
have a go at some vmod objects dev doc (not new for 6.1)
diff --git a/doc/sphinx/reference/vmod.rst b/doc/sphinx/reference/vmod.rst
index b9c0fcfc8..657585f82 100644
--- a/doc/sphinx/reference/vmod.rst
+++ b/doc/sphinx/reference/vmod.rst
@@ -178,6 +178,73 @@ declarations:
Note that in particular also ``PRIV_*`` arguments (which are
unnamed by definition) are passed as ``arg``\ `n`
+.. _ref-vmod-vcl-c-objects:
+
+Objects and methods
+-------------------
+
+Varnish also supports a simple object model for vmods. Objects and
+methods are declared in the vcc file as::
+
+ $Object class(`constructor arguments`)
+ $Method .method(`method arguments`)
+
+
+For declared object classes of a vmod, object instances can then be
+created in ``vcl_init { }`` using the ``new`` statement::
+
+ sub vcl_init {
+ new foo = vmod.class(...);
+ }
+
+and have their methods called anywhere (including in ``vcl_init {}``
+after the instantiation)::
+
+ sub somewhere {
+ foo.method(...);
+ }
+
+Object instances are represented as pointers to vmod-implemented C
+structs. Varnish only provides space to store the address of object
+instances and ensures that the right object address gets passed to C
+functions implementing methods.
+
+ * Objects' scope and lifetime are the vcl
+
+ * Objects can only be created in ``vcl_init {}`` and have
+ their destructors called by varnish after ``vcl_fini {}``
+ has completed.
+
+vmod authors are advised to understand the prototypes in the
+`vmodtool`\ -generated ``vcc_if.c`` file:
+
+ * For ``$Object`` declarations, a constructor and destructor
+ function must be implemented
+
+ * The constructor is named by the suffix ``__init``, always is
+ of ``VOID`` return type and has the following arguments
+ before the vcc-declared parameters:
+
+ * ``VRT_CTX`` as usual
+ * a pointer-pointer to return the address of the created
+ oject
+ * a string containing the vcl name of the object instance
+
+ * The destructor is named by the suffix ``__fini``, always is
+ of ``VOID`` return type and has a single argument, the
+ pointer-pointer to the address of the object. The destructor
+ is expected clear the address of the object stored in that
+ pointer-pointer.
+
+ * Methods gain the pointer to the object as an argument after
+ the ``VRT_CTX``.
+
+As varnish is in no way involved in managing object instances other
+than passing their addresses, vmods need to implement all aspects of
+managing instances, in particular their memory management. As the
+lifetime of object instances is the vcl, they will usually be
+allocated from the heap.
+
.. _ref-vmod-vcl-c-types:
VCL and C data types
@@ -439,6 +506,20 @@ malloc would look like this::
The per-call vmod_privs are freed before the per-vcl vmod_priv.
+Note on use with objects:
+
+``PRIV_TASK`` and ``PRIV_TOP`` arguments are not per object instance,
+but still per vmod as for ordinary vmod functions. Thus, vmods
+requiring per-task / per top-request state for object instances need
+to implement other means to associate storage with object instances.
+
+Using ``VRT_priv_task()`` to maintin per object instance state is a
+convenient yet inofficial interface which was not originally intended
+for this purpose and will likely be replaced with a more suitable
+interface.
+
+
+
.. _ref-vmod-event-functions:
Event functions
@@ -511,6 +592,7 @@ In the case where properly releasing resources may take some time, you can
opt for an asynchronous worker, either by spawning a thread and tracking it, or
by using Varnish's worker pools.
+
When to lock, and when not to lock
==================================
More information about the varnish-commit
mailing list