Merge remote-tracking branch 'origin/master' into topic/seth/metrics-merge

doc/scripts/builtins.rst

@@ -417,10 +417,6 @@ The Bro scripting language supports the following built-in types.
     Writing to files like this for logging usually isn't recommended, for better
     logging support see :doc:`/logging`.
 
-.. bro:type:: func
-
-    See :bro:type:`function`.
-
 .. bro:type:: function
 
     Function types in Bro are declared using::
@@ -504,6 +500,74 @@ The Bro scripting language supports the following built-in types.
     identifier and the body of each will be executed in turn.  Ordering
     of execution can be influenced with :bro:attr:`&priority`.
 
+.. bro:type:: hook
+
+    A hook is another flavor of function that shares characteristics of
+    both a :bro:type:`function` and a :bro:type:`event`.  They are like
+    events in that many handler bodies can be defined for the same hook
+    identifier, they have no return vale, and the order of execution
+    can be enforced with :bro:attr:`&priority`.  They are more like
+    functions in the way they are invoked/called, because, unlike
+    events, their execution is immediate and they do not get scheduled
+    through an event queue.  Also, a unique feature of a hook is that
+    a given hook handler body can short-circuit the execution of
+    remaining hook handlers simply by exiting from the body as a result
+    of a ``break`` statement (as opposed to a ``return`` or just
+    reaching the end of the body).
+
+    A hook type is declared like::
+
+        hook( argument* )
+
+    where *argument* is a (possibly empty) comma-separated list of
+    arguments.  For example:
+
+    .. code:: bro
+
+        global myhook: hook(s: string)
+
+    Here ``myhook`` is the hook type identifier and no hook handler
+    bodies have been defined for it yet.  To define some hook handler
+    bodies the syntax looks like:
+
+    .. code:: bro
+
+        hook myhook(s: string) &priority=10
+            {
+            print "priority 10 myhook handler", s;
+            s = "bye";
+            }
+
+        hook myhook(s: string)
+            {
+            print "break out of myhook handling", s;
+            break;
+            }
+
+        hook myhook(s: string) &priority=-5
+            {
+            print "not going to happen", s;
+            }
+
+    Note that, although the first (forward) declaration of ``myhook`` as
+    a hook type isn't strictly required, when it is provided, the
+    argument types must match.
+
+    To invoke immediate execution of all hook handler bodies, a ``hook``
+    statement must be used:
+
+    .. code:: bro
+
+        hook myhook("hi");
+
+    And the output would like like::
+
+        priority 10 myhook handler, hi
+        break out of myhook handling, bye
+
+    Note how the modification to arguments can be seen by remaining
+    hook handlers.
+
 Attributes
 ----------