summaryrefslogtreecommitdiffstats
path: root/docs/gettingstarted/developers/vlib.md
diff options
context:
space:
mode:
authorDave Barach <dave@barachs.net>2019-05-16 12:16:29 -0400
committerFlorin Coras <florin.coras@gmail.com>2019-05-16 16:59:19 +0000
commit8fa01c17aa65c03b1f25f9accaa5bb0f9d0862c4 (patch)
treec9bae80c72330d8fdeafa56999ee33eca7e5c908 /docs/gettingstarted/developers/vlib.md
parentf8d50682cd1245f6f5ce4c846ca6f1bdc11255a6 (diff)
DOC ONLY: document VLIB_INIT_FUNCTION scheme
Change-Id: I15c4256621da6c8d47b1a7c41755ee6587996757 Signed-off-by: Dave Barach <dave@barachs.net>
Diffstat (limited to 'docs/gettingstarted/developers/vlib.md')
-rw-r--r--docs/gettingstarted/developers/vlib.md53
1 files changed, 49 insertions, 4 deletions
diff --git a/docs/gettingstarted/developers/vlib.md b/docs/gettingstarted/developers/vlib.md
index f25b0bab54b..462168618b2 100644
--- a/docs/gettingstarted/developers/vlib.md
+++ b/docs/gettingstarted/developers/vlib.md
@@ -15,10 +15,11 @@ Init function discovery
vlib applications register for various \[initialization\] events by
placing structures and \_\_attribute\_\_((constructor)) functions into
the image. At appropriate times, the vlib framework walks
-constructor-generated singly-linked structure lists, calling the
-indicated functions. vlib applications create graph nodes, add CLI
-functions, start cooperative multi-tasking threads, etc. etc. using this
-mechanism.
+constructor-generated singly-linked structure lists, performs a
+topological sort based on specified constraints, and calls the
+indicated functions. Vlib applications create graph nodes, add CLI
+functions, start cooperative multi-tasking threads, etc. etc. using
+this mechanism.
vlib applications invariably include a number of VLIB\_INIT\_FUNCTION
(my\_init\_function) macros.
@@ -32,6 +33,50 @@ other libraries such as VNET. In the latter case, it may be necessary to
explicitly reference symbol(s) otherwise large portions of the library
may be AWOL at runtime.
+### Init function construction and constraint specification
+
+It's easy to add an init function:
+
+```
+ static clib_error_t *my_init_function (vlib_main_t *vm)
+ {
+ /* ... initialize things ... */
+
+ return 0; // or return clib_error_return (0, "BROKEN!");
+ }
+ VLIB_INIT_FUNCTION(my_init_function);
+```
+
+As given, my_init_function will be executed "at some point," but with
+no ordering guarantees.
+
+Specifying ordering constraints is easy:
+
+```
+ VLIB_INIT_FUNCTION(my_init_function) =
+ {
+ .runs_before = VLIB_INITS("we_run_before_function_1",
+ "we_run_before_function_2"),
+ .runs_after = VLIB_INITS("we_run_after_function_1",
+ "we_run_after_function_2),
+ };
+```
+
+It's also easy to specify bulk ordering constraints of the form "a
+then b then c then d":
+
+```
+ VLIB_INIT_FUNCTION(my_init_function) =
+ {
+ .init_order = VLIB_INITS("a", "b", "c", "d"),
+ };
+```
+
+It's OK to specify all three sorts of ordering constraints for a
+single init function, although it's hard to imagine why it would be
+necessary.
+
+
Node Graph Initialization
-------------------------