[4.1] 929be35 Rearrange and minor updates
Federico G. Schwindt
fgsch at lodoss.net
Fri Sep 4 15:54:54 CEST 2015
commit 929be359b4757ff2f11f6f28fd539338c917c4b7
Author: Federico G. Schwindt <fgsch at lodoss.net>
Date: Fri Aug 14 15:24:08 2015 +0100
Rearrange and minor updates
diff --git a/doc/sphinx/reference/vmod.rst b/doc/sphinx/reference/vmod.rst
index 6053685..893a1c7 100644
--- a/doc/sphinx/reference/vmod.rst
+++ b/doc/sphinx/reference/vmod.rst
@@ -56,22 +56,23 @@ The std VMODs vmod.vcc file looks somewhat like this::
$Function STRING tolower(STRING_LIST)
$Function VOID set_ip_tos(INT)
-The first line gives the name of the module, nothing special there.
+The first line gives the name of the module and the manual section where
+the documentation will reside.
The second line specifies an optional "Event" function, which will be
-called whenever a VCL program which imports this VMOD is initially loaded
-or transitions to any of the warm, active, cold and discarded states.
+called whenever a VCL program which imports this VMOD is loaded or
+transitions to any of the warm, active, cold or discarded states.
More on this below.
-The next three lines specify two functions in the VMOD, along with the
-types of the arguments, and that is probably where the hardest bit
-of writing a VMOD is to be found, so we will talk about that at length
-in a moment.
+The next three lines define three functions in the VMOD, along with the
+types of the arguments, and that is probably where the hardest bit of
+writing a VMOD is to be found, so we will talk about that at length in
+a moment.
Notice that the third function returns VOID, that makes it a "procedure"
-in VCL lingo, meaning that it cannot be used in expressions, right
-side of assignments and such places. Instead it can be used as a
-primary action, something functions which return a value can not::
+in VCL lingo, meaning that it cannot be used in expressions, right side
+of assignments and such. Instead it can be used as a primary action,
+something functions which return a value can not::
sub vcl_recv {
std.set_ip_tos(32);
@@ -98,8 +99,8 @@ For the std VMOD, the compiled vcc_if.h file looks like this::
vmod_event_f event_function;
-Those are your C prototypes. Notice the ``vmod_`` prefix on the function
-names and the C-types as arguments.
+Those are your C prototypes. Notice the ``vmod_`` prefix on the
+function names.
.. _ref-vmod-vcl-c-types:
@@ -111,40 +112,91 @@ VCL data types are targeted at the job, so for instance, we have data
types like "DURATION" and "HEADER", but they all have some kind of C
language representation. Here is a description of them.
-All but the STRING_LIST type have typedefs: VCL_INT, VCL_REAL etc.
+All but the PRIV and STRING_LIST types have typedefs: VCL_INT, VCL_REAL,
+etc.
-INT
- C-type: ``long``
+BACKEND
+ C-type: ``const struct director *``
- An integer as we know and love them.
+ A type for backend and director implementations. See
+ :ref:`ref-writing-a-director`.
-REAL
+BLOB
+ C-type: ``const struct vmod_priv *``
+
+ An opaque type to pass random bits of memory between VMOD
+ functions.
+
+BOOL
+ C-type: ``unsigned``
+
+ Zero means false, anything else means true.
+
+BYTES
C-type: ``double``
- A floating point value.
+ Unit: bytes.
+
+ A storage space, as in 1024 bytes.
DURATION
C-type: ``double``
- Unit: seconds
+ Unit: seconds.
A time interval, as in 25 seconds.
+ENUM
+ C-type: ``const char *``
+
+ TODO
+
+HEADER
+ C-type: ``const struct gethdr_s *``
+
+ These are VCL compiler generated constants referencing a
+ particular header in a particular HTTP entity, for instance
+ ``req.http.cookie`` or ``beresp.http.last-modified``. By passing
+ a reference to the header, the VMOD code can both read and write
+ the header in question.
+
+ If the header was passed as STRING, the VMOD code only sees
+ the value, but not where it came from.
+
+HTTP
+ C-type: ``struct http *``
+
+ TODO
+
+INT
+ C-type: ``long``
+
+ A (long) integer as we know and love them.
+
+IP
+ C-type: ``const struct suckaddr *``
+
+ This is an opaque type, see the ``include/vsa.h`` file for
+ which primitives we support on this type.
+
+REAL
+ C-type: ``double``
+
+ A floating point value.
+
TIME
C-type: ``double``
- Unit: seconds since UNIX epoch
+ Unit: seconds since UNIX epoch.
- An absolute time, as in 1284401161. When used in a string
- context is formatted as "Mon, 13 Sep 2010 19:06:01 GMT".
+ An absolute time, as in 1284401161.
STRING
C-type: ``const char *``
A NUL-terminated text-string.
- Can be NULL to indicate that the nonexistent string, for
- instance::
+ Can be NULL to indicate a nonexistent string, for instance in::
mymod.foo(req.http.foobar);
@@ -192,58 +244,23 @@ STRING_LIST
and make sure your workspace_client and workspace_backend params
are big enough.
-PRIV_VCL
- See :ref:`ref-vmod-private-pointers` below
-
-PRIV_CALL
- See :ref:`ref-vmod-private-pointers` below
-
-PRIV_TASK
- See :ref:`ref-vmod-private-pointers` below
-
-PRIV_TOP
- See :ref:`ref-vmod-private-pointers` below
-
VOID
C-type: ``void``
Can only be used for return-value, which makes the function a VCL
procedure.
-HEADER
- C-type: ``const struct gethdr_s *``
-
- These are VCL compiler generated constants referencing
- a particular header in a particular HTTP entity, for instance
- ``req.http.cookie`` or ``beresp.http.last-modified``.
- By passing a reference to the header, the VMOD code can
- both read and write the header in question.
-
- If the header was passed as STRING, the VMOD code only sees
- the value, but not where it came from.
-
-IP
- C-type: ``const struct suckaddr *``
-
- This is an opaque type, see the ``include/vsa.h`` file for
- which primitives we support on this type.
-
-BOOL
- C-type: ``unsigned``
-
- Zero means false, anything else means true.
-
-BLOB
- C-type: ``const struct vmod_priv *``
+PRIV_VCL
+ See :ref:`ref-vmod-private-pointers` below.
- An opaque type to pass random bits of memory between VMOD
- functions.
+PRIV_CALL
+ See :ref:`ref-vmod-private-pointers` below.
-BACKEND
- C-type: ``const struct director *``
+PRIV_TASK
+ See :ref:`ref-vmod-private-pointers` below.
- A type for backend and director implementations. See
- :ref:`ref-writing-a-director`.
+PRIV_TOP
+ See :ref:`ref-vmod-private-pointers` below.
.. _ref-vmod-private-pointers:
More information about the varnish-commit
mailing list