Changes between Initial Version and Version 1 of Bithenge/Library

Timestamp:

2012-08-20T18:59:29Z (12 years ago)

Author:

Sean Bartell

Comment:

—

Bithenge/Library

@@ +1 @@
+= Bithenge Library =
+
+[[PageOutline(2-3)]]
+
+This page gives an overview of the [[Bithenge]] library API and internals.
+Detailed documentation can be found in the source code’s Doxygen comments.
+
+== Conventions ==
+
+=== Names ===
+
+All public functions and types have names starting with `bithenge_`.
+
+=== Error handling ===
+
+Almost all Bithenge functions return an integer error code. It will be EOK on
+success or an error code from `errno.h` on failure. Even if an error occurs,
+functions will still free or dereference their arguments as documented.
+
+=== Reference counting ===
+
+Nodes, expressions, transforms, and scopes use reference counting. For
+instance, functions that produce a node (through a `bithenge_node_t **`
+parameter) create a new reference to the node; you are responsible for ensuring
+the reference count is eventually decremented. The reference count can be
+incremented with `bithenge_xxx_inc_ref` and decremented with
+`bithenge_xxx_dec_ref`.
+
+If a function’s documentation says it “takes [ownership of] a reference” to an
+object, the function guarantees the object’s reference count will eventually be
+decremented, even if an error occurs.  Therefore, if you create an object only
+to immediately pass it to such a function, you do not need to change its
+reference count. 
+
+=== Polymorphism ===
+
+Blob nodes, internal nodes, expressions, and transforms are polymorphic. We
+will use transforms as an example, but the others are similar. Each transform
+implementation has its own `struct`, including a `bithenge_transform_t` member,
+and its own static `bithenge_transform_ops_t` instance. When a transform is
+created, it calls `bithenge_transform_init` on the `bithenge_transform_t` and
+gives it a pointer to the `bithenge_transform_ops_t` instance. It then returns
+a pointer to the `bithenge_transform_t` to the caller. When the caller uses a
+function on the `bithenge_transform_t *`, it automatically looks in the
+`bithenge_transform_ops_t` for the transform‐specific implementation.
+
+== Main types ==
+
+=== Nodes ===
+
+Integer, boolean, and string nodes are trivial. Blob and internal nodes are
+polymorphic; each node has its own functions to access its contents. This means
+calculating the node’s contents can be delayed until the contents are needed.
+
+=== Transforms ===
+
+The primary method of transforms is `apply`, which applies a transform to an
+input tree and creates an output tree. When a transform takes a blob node as
+input, it is sometimes necessary to determine the prefix of a given blob that
+can be used as input to the transform; the method `prefix_length` can be used
+for this. Alternatively, a `prefix_apply` method can do both at once,
+substituting for or supplementing `apply` and `prefix_length`. All three of
+these methods take a scope; see below.
+
+=== Expressions ===
+
+The only method of expressions is `evaluate`, which evaluates the expression in
+a scope to create an output node. Expressions can be considered similar to
+transforms, except that they have no input node.
+
+=== Scopes ===
+
+Scopes keep track of all information needed by transforms and expressions other
+than transforms’ input trees. This includes parameters, nodes being created,
+input nodes, and error messages.
+
+== Main functions ==
+
+Aside from functions directly related to the types above, Bithenge has several
+other important functions:
+- `bithenge_parse_script` parses a Bithenge script file to create a transform.
+- `bithenge_node_from_source` creates a node based on a string, such as
+  `block:bd/initrd`.
+- `bithenge_print_node` prints nodes in human‐readable formats.
+
+The [https://bazaar.launchpad.net/~wtachi/helenos/bithenge/view/head:/uspace/app/bithenge/test.c test.c]
+program included with Bithenge is a simple demonstration of all of these functions.
+
+== Testing ==
+
+In HelenOS, Bithenge can be tested by running `batch test.bdsh` in the
+`/src/bithenge` directory. If it runs to the end and prints "Success!",
+Bithenge worked correctly on the example files.
+
+In Linux, more advanced testing is possible. Compile with
+`COVERAGE=y FAILURE=y make` and run `test.sh` with Valgrind installed. Bithenge
+will use failure injection to test much of the error handling code, in addition
+to the main paths.