fix example code in wrap_op_checker() doc
authorZefram <zefram@fysh.org>
Mon, 31 Jul 2017 10:10:16 +0000 (11:10 +0100)
committerZefram <zefram@fysh.org>
Mon, 31 Jul 2017 10:10:16 +0000 (11:10 +0100)
Commit b93e7f0e1e15a1bbbcd9031bc4b66a5c60686eca added some code fragments
to the documentation of this function in order to explain it, but
got part of it wrong, confusing a pointer with the thing it points to.
Correct that, and reformulate the fragments of code into a more coherent
single example.

op.c

diff --git a/op.c b/op.c
index 69cc693..ff78e95 100644 (file)
--- a/op.c
+++ b/op.c
@@ -15375,18 +15375,6 @@ pointer to the next function in the chain will be stored.  The value of
 C<new_pointer> is written into the L</PL_check> array, while the value
 previously stored there is written to C<*old_checker_p>.
 
-The function should be defined like this:
-
-    static OP *new_checker(pTHX_ OP *op) { ... }
-
-It is intended to be called in this manner:
-
-    new_checker(aTHX_ op)
-
-C<old_checker_p> should be defined like this:
-
-    static Perl_check_t old_checker_p;
-
 L</PL_check> is global to an entire process, and a module wishing to
 hook op checking may find itself invoked more than once per process,
 typically in different threads.  To handle that situation, this function
@@ -15408,6 +15396,19 @@ decides not to do anything special with an op that it is given (which
 is the usual case for most uses of op check hooking), it must chain the
 check function referenced by C<*old_checker_p>.
 
+Taken all together, XS code to hook an op checker should typically look
+something like this:
+
+    static Perl_check_t nxck_frob;
+    static OP *myck_frob(pTHX_ OP *op) {
+       ...
+       op = nxck_frob(aTHX_ op);
+       ...
+       return op;
+    }
+    BOOT:
+       wrap_op_checker(OP_FROB, myck_frob, &nxck_frob);
+
 If you want to influence compilation of calls to a specific subroutine,
 then use L</cv_set_call_checker> rather than hooking checking of all
 C<entersub> ops.