Code Review

# Code Review 1

### Some background...

This is one of the functions exported from the `H5B.c` file that implements a B-link-tree class without worrying about concurrency yet (thus the `Note:' in the function prologue). The `H5B.c` file provides the basic machinery for operating on generic B-trees, but it isn't much use by itself. Various subclasses of the B-tree (like symbol tables or indirect storage) provide their own interface and back end to this function. For instance, `H5G_stab_find()` takes a symbol table OID and a name and calls `H5B_find()` with an appropriate `udata` argument that eventually gets passed to the `H5G_stab_find()` function.

``

     1 /*-------------------------------------------------------------------------
     2  * Function:    H5B_find
     3  *
     4  * Purpose:     Locate the specified information in a B-tree and return
     5  *              that information by filling in fields of the caller-supplied
     6  *              UDATA pointer depending on the type of leaf node
     7  *              requested.  The UDATA can point to additional data passed
     8  *              to the key comparison function.
     9  *
    10  * Note:        This function does not follow the left/right sibling
    11  *              pointers since it assumes that all nodes can be reached
    12  *              from the parent node.
    13  *
    14  * Return:      Success:        SUCCEED if found, values returned through the
    15  *                              UDATA argument.
    16  *
    17  *              Failure:        FAIL if not found, UDATA is undefined.
    18  *
    19  * Programmer:  Robb Matzke
    20  *              matzke@llnl.gov
    21  *              Jun 23 1997
    22  *
    23  * Modifications:
    24  *
    25  *-------------------------------------------------------------------------
    26  */
    27 herr_t
    28 H5B_find (H5F_t *f, const H5B_class_t *type, const haddr_t *addr, void *udata)
    29 {
    30    H5B_t        *bt=NULL;
    31    intn         idx=-1, lt=0, rt, cmp=1;
    32    int          ret_value = FAIL;

All pointer arguments are initialized when defined. I don't worry much about non-pointers because it's usually obvious when the value isn't initialized.

``

    33
    34    FUNC_ENTER (H5B_find, NULL, FAIL);
    35
    36    /*
    37     * Check arguments.
    38     */
    39    assert (f);
    40    assert (type);
    41    assert (type->decode);
    42    assert (type->cmp3);
    43    assert (type->found);
    44    assert (addr && H5F_addr_defined (addr));

I use `assert` to check invariant conditions. At this level of the library, none of these assertions should fail unless something is majorly wrong. The arguments should have already been checked by higher layers. It also provides documentation about what arguments might be optional.

``

    45
    46    /*
    47     * Perform a binary search to locate the child which contains
    48     * the thing for which we're searching.
    49     */
    50    if (NULL==(bt=H5AC_protect (f, H5AC_BT, addr, type, udata))) {
    51       HGOTO_ERROR (H5E_BTREE, H5E_CANTLOAD, FAIL);
    52    }

You'll see this quite often in the low-level stuff and it's documented in the `H5AC.c` file. The `H5AC_protect` insures that the B-tree node (which inherits from the H5AC package) whose OID is `addr` is locked into memory for the duration of this function (see the `H5AC_unprotect` on line 90). Most likely, if this node has been accessed in the not-to-distant past, it will still be in memory and the `H5AC_protect` is almost a no-op. If cache debugging is compiled in, then the protect also prevents other parts of the library from accessing the node while this function is protecting it, so this function can allow the node to be in an inconsistent state while calling other parts of the library.

The alternative is to call the slighlty cheaper `H5AC_find` and assume that the pointer it returns is valid only until some other library function is called, but since we're accessing the pointer throughout this function, I chose to use the simpler protect scheme. All protected objects must be unprotected before the file is closed, thus the use of `HGOTO_ERROR` instead of `HRETURN_ERROR`.

``

    53    rt = bt->nchildren;
    54
    55    while (lt<rt && cmp) {
    56       idx = (lt + rt) / 2;
    57       if (H5B_decode_keys (f, bt, idx)<0) {
    58          HGOTO_ERROR (H5E_BTREE, H5E_CANTDECODE, FAIL);
    59       }
    60
    61       /* compare */
    62       if ((cmp=(type->cmp3)(f, bt->key[idx].nkey, udata,
    63                             bt->key[idx+1].nkey))<0) {
    64          rt = idx;
    65       } else {
    66          lt = idx+1;
    67       }
    68    }
    69    if (cmp) {
    70       HGOTO_ERROR (H5E_BTREE, H5E_NOTFOUND, FAIL);
    71    }

Code is arranged in paragraphs with a comment starting each paragraph. The previous paragraph is a standard binary search algorithm. The `(type->cmp3)()` is an indirect function call into the subclass of the B-tree. All indirect function calls have the function part in parentheses to document that it's indirect (quite obvious here, but not so obvious when the function is a variable).

It's also my standard practice to have side effects in conditional expressions because I can write code faster and it's more apparent to me what the condition is testing. But if I have an assignment in a conditional expr, then I use an extra set of parens even if they're not required (usually they are, as in this case) so it's clear that I meant `=` instead of `==`.

``

    72
    73    /*
    74     * Follow the link to the subtree or to the data node.
    75     */
    76    assert (idx>=0 && idxnchildren);
    77    if (bt->level > 0) {
    78       if ((ret_value = H5B_find (f, type, bt->child+idx, udata))<0) {
    79          HGOTO_ERROR (H5E_BTREE, H5E_NOTFOUND, FAIL);
    80       }
    81    } else {
    82       ret_value = (type->found)(f, bt->child+idx, bt->key[idx].nkey,
    83                                 udata, bt->key[idx+1].nkey);
    84       if (ret_value<0) {
    85          HGOTO_ERROR (H5E_BTREE, H5E_NOTFOUND, FAIL);
    86       }
    87    }

Here I broke the "side effect in conditional" rule, which I sometimes do if the expression is so long that the `<0` gets lost at the end. Another thing to note is that success/failure is always determined by comparing with zero instead of `SUCCEED` or `FAIL`. I do this because occassionally one might want to return other meaningful values (always non-negative) or distinguish between various types of failure (always negative).

``

    88
    89 done:
    90    if (bt && H5AC_unprotect (f, H5AC_BT, addr, bt)<0) {
    91       HRETURN_ERROR (H5E_BTREE, H5E_PROTECT, FAIL);
    92    }
    93    FUNC_LEAVE (ret_value);
    94 }

For lack of a better way to handle errors during error cleanup, I just call the `HRETURN_ERROR` macro even though it will make the error stack not quite right. I also use short circuiting boolean operators instead of nested `if` statements since that's standard C practice.

# Code Review 2

The following code is an API function from the H5F package...

``

     1 /*--------------------------------------------------------------------------
     2  NAME
     3     H5Fflush
     4
     5  PURPOSE
     6     Flush all cached data to disk and optionally invalidates all cached
     7     data.
     8
     9  USAGE
    10     herr_t H5Fflush(fid, invalidate)
    11         hid_t fid;              IN: File ID of file to close.
    12         hbool_t invalidate;     IN: Invalidate all of the cache?
    13
    14  ERRORS
    15     ARGS      BADTYPE       Not a file atom.
    16     ATOM      BADATOM       Can't get file struct.
    17     CACHE     CANTFLUSH     Flush failed.
    18
    19  RETURNS
    20     SUCCEED/FAIL
    21
    22  DESCRIPTION
    23         This function flushes all cached data to disk and, if INVALIDATE
    24     is non-zero, removes cached objects from the cache so they must be
    25     re-read from the file on the next access to the object.
    26
    27  MODIFICATIONS:
    28 --------------------------------------------------------------------------*/

An API prologue is used for each API function instead of my normal function prologue. I use the prologue from Code Review 1 for non-API functions because it's more suited to C programmers, it requires less work to keep it synchronized with the code, and I have better editing tools for it.

``

    29 herr_t
    30 H5Fflush (hid_t fid, hbool_t invalidate)
    31 {
    32    H5F_t        *file = NULL;
    33
    34    FUNC_ENTER (H5Fflush, H5F_init_interface, FAIL);
    35    H5ECLEAR;

API functions are never called internally, therefore I always clear the error stack before doing anything.

``

    36
    37    /* check arguments */
    38    if (H5_FILE!=H5Aatom_group (fid)) {
    39       HRETURN_ERROR (H5E_ARGS, H5E_BADTYPE, FAIL); /*not a file atom*/
    40    }
    41    if (NULL==(file=H5Aatom_object (fid))) {
    42       HRETURN_ERROR (H5E_ATOM, H5E_BADATOM, FAIL); /*can't get file struct*/
    43    }

If something is wrong with the arguments then we raise an error. We never `assert` arguments at this level. We also convert atoms to pointers since atoms are really just a pointer-hiding mechanism. Functions that can be called internally always have pointer arguments instead of atoms because (1) then they don't have to always convert atoms to pointers, and (2) the various pointer data types provide more documentation and type checking than just an `hid_t` type.

``

    44
    45    /* do work */
    46    if (H5F_flush (file, invalidate)<0) {
    47       HRETURN_ERROR (H5E_CACHE, H5E_CANTFLUSH, FAIL); /*flush failed*/
    48    }

An internal version of the function does the real work. That internal version calls `assert` to check/document it's arguments and can be called from other library functions.

``

    49
    50    FUNC_LEAVE (SUCCEED);
    51 }

Last modified: Mon Nov 10 15:33:33 EST 1997