Changes between Initial Version and Version 1 of Bithenge/Library

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


  • Bithenge/Library

    v1 v1  
     1= Bithenge Library =
     5This page gives an overview of the [[Bithenge]] library API and internals.
     6Detailed documentation can be found in the source code’s Doxygen comments.
     8== Conventions ==
     10=== Names ===
     12All public functions and types have names starting with `bithenge_`.
     14=== Error handling ===
     16Almost all Bithenge functions return an integer error code. It will be EOK on
     17success or an error code from `errno.h` on failure. Even if an error occurs,
     18functions will still free or dereference their arguments as documented.
     20=== Reference counting ===
     22Nodes, expressions, transforms, and scopes use reference counting. For
     23instance, functions that produce a node (through a `bithenge_node_t **`
     24parameter) create a new reference to the node; you are responsible for ensuring
     25the reference count is eventually decremented. The reference count can be
     26incremented with `bithenge_xxx_inc_ref` and decremented with
     29If a function’s documentation says it “takes [ownership of] a reference” to an
     30object, the function guarantees the object’s reference count will eventually be
     31decremented, even if an error occurs.  Therefore, if you create an object only
     32to immediately pass it to such a function, you do not need to change its
     33reference count.
     35=== Polymorphism ===
     37Blob nodes, internal nodes, expressions, and transforms are polymorphic. We
     38will use transforms as an example, but the others are similar. Each transform
     39implementation has its own `struct`, including a `bithenge_transform_t` member,
     40and its own static `bithenge_transform_ops_t` instance. When a transform is
     41created, it calls `bithenge_transform_init` on the `bithenge_transform_t` and
     42gives it a pointer to the `bithenge_transform_ops_t` instance. It then returns
     43a pointer to the `bithenge_transform_t` to the caller. When the caller uses a
     44function on the `bithenge_transform_t *`, it automatically looks in the
     45`bithenge_transform_ops_t` for the transform‐specific implementation.
     47== Main types ==
     49=== Nodes ===
     51Integer, boolean, and string nodes are trivial. Blob and internal nodes are
     52polymorphic; each node has its own functions to access its contents. This means
     53calculating the node’s contents can be delayed until the contents are needed.
     55=== Transforms ===
     57The primary method of transforms is `apply`, which applies a transform to an
     58input tree and creates an output tree. When a transform takes a blob node as
     59input, it is sometimes necessary to determine the prefix of a given blob that
     60can be used as input to the transform; the method `prefix_length` can be used
     61for this. Alternatively, a `prefix_apply` method can do both at once,
     62substituting for or supplementing `apply` and `prefix_length`. All three of
     63these methods take a scope; see below.
     65=== Expressions ===
     67The only method of expressions is `evaluate`, which evaluates the expression in
     68a scope to create an output node. Expressions can be considered similar to
     69transforms, except that they have no input node.
     71=== Scopes ===
     73Scopes keep track of all information needed by transforms and expressions other
     74than transforms’ input trees. This includes parameters, nodes being created,
     75input nodes, and error messages.
     77== Main functions ==
     79Aside from functions directly related to the types above, Bithenge has several
     80other important functions:
     81- `bithenge_parse_script` parses a Bithenge script file to create a transform.
     82- `bithenge_node_from_source` creates a node based on a string, such as
     83  `block:bd/initrd`.
     84- `bithenge_print_node` prints nodes in human‐readable formats.
     86The [ test.c]
     87program included with Bithenge is a simple demonstration of all of these functions.
     89== Testing ==
     91In HelenOS, Bithenge can be tested by running `batch test.bdsh` in the
     92`/src/bithenge` directory. If it runs to the end and prints "Success!",
     93Bithenge worked correctly on the example files.
     95In Linux, more advanced testing is possible. Compile with
     96`COVERAGE=y FAILURE=y make` and run `` with Valgrind installed. Bithenge
     97will use failure injection to test much of the error handling code, in addition
     98to the main paths.