tmstat.h

/*
 * Copyright (c) 2013, F5 Networks, Inc.
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met: 
 * 
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer. 
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution. 
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 * 
 * The views and conclusions contained in the software and documentation are
 * those of the authors and should not be interpreted as representing official
 * policies, either expressed or implied, of F5 Networks, Inc.
 *
 * This module provides statistics publishing and collation services for
 * multiple daemons on a local machine.  It uses the familiar concepts
 * of tables, rows and columns.
 *
 * It also provides the concept of a segment, which is a logical
 * collection of tables.  Segments may either be read or written,
 * but not both.  A writable segment may be published to a public
 * directory, and where it may be subscribed to in a read-only fashion.
 * Writable segments may either be created from scratch or generated by
 * taking a copy of a read-only segment.
 *
 * A union segment is a read-only segment that gives the merged
 * representation of several segments.  This allows a consumer to view
 * multiple publisher's segments as a single database.
 *
 * Segments are merged together via the merge rules contained within
 * the segments themselves. In short, all tables with the same name
 * are merged -- the table metadata instructs how to merge its rows.
 * Basically, all rows with the same key fields are merged and each column
 * describes how to merge its field (e.g. take the sum of all fields).
 *
 * This system allows for multiple directories (publisher sets).  This
 * allows for systems which wish to cascade their merges.  For example,
 * one subsystem may want to merge its various internal segments and
 * present a unified subsystem segment to the system at large.  This may
 * be for efficiency or architectural reasons.
 *
 */
#ifndef __TMSTAT_TMSTAT_H__
#define __TMSTAT_TMSTAT_H__

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Parameters
 */
#define TMSTAT_DIR_PRIVATE      "private"     //!< path of private segment.
#define TMSTAT_DIR_PUBLISH      "blade"       //!< Default publish directory.
#define TMSTAT_DIR_SUBSCRIBE    "cluster"     //!< Default subscribe directory.
#define TMSTAT_PATH             "/var/tmstat" //!< Memory filesystem base.
#define TMSTAT_PATHED_NAMELEN   256           //!< Suggested for field lengths that are folderized
#define TMSTAT_UNPATHED_NAMELEN 64            //!< Suggested for unfolderized field lengths
#define TMSTAT_MAX_NAME         48            //!< Max column/table name len.

/**
 * Statistics segment handle.
 */
#ifdef __cplusplus
typedef struct __TMSTAT *TMSTAT;
#else
typedef struct TMSTAT *TMSTAT;
#endif

/**
 * Statistics table handle.  Handles are only given to writers.
 * Readers always refer to tables by name.
 */
#ifdef __cplusplus
typedef struct __TMTABLE *TMTABLE;
#else
typedef struct TMTABLE *TMTABLE;
#endif

/**
 * Column descriptor.
 */
#ifndef __cplusplus
typedef struct TMCOL *TMCOL;
#endif

/**
 * Row handle.
 */
#ifdef __cplusplus
typedef struct __TMROW *TMROW;
#else
typedef struct TMROW *TMROW;
#endif

/**
 * Parser context.
 */
#ifdef __cplusplus
typedef struct __TMSTAT_EVAL *TMSTAT_EVAL;
#else
typedef struct TMSTAT_EVAL *TMSTAT_EVAL;
#endif

#ifdef F5_CFG_TLS
#define THREAD __thread
#define GLOBALSET   __attribute__((__section__("set_global")))
#else
#define THREAD
#define GLOBALSET
#endif /* F5_CFG_TLS */

/**
 * Basic types.
 *
 * Types are described by how they should be presented to a human.
 *
 * Sizing information is not captured in the type itself; instead it is
 * stored seperately.  For example, a TMSTAT_T_SIGNED field may be 1 or 4
 * bytes in size.  When the fields are merged, the system will promote the
 * field to the largest size present in any of the children fields.
 *
 * Examples of each format are:
 *
 *          SIGNED              -42
 *          UNSIGNED            31,337
 *          TEXT                Hello, world!
 *          BIN                 0001:0010 0011:0100
 *          DEC                 127.0.0.1
 *          HEX                 00:05:4E:4C:E9:ED
 */
enum tmstat_type {
    TMSTAT_T_HIDDEN     = 0,    //!< Data to be ignored by the stats system.
    TMSTAT_T_SIGNED     = 1,    //!< Signed integer value.
    TMSTAT_T_UNSIGNED   = 2,    //!< Unsigned integer value.
    TMSTAT_T_TEXT       = 3,    //!< Human-readable text (ISO 646 compatible).
    TMSTAT_T_BIN        = 4,    //!< Binary stream (e.g., bit set).
    TMSTAT_T_DEC        = 5,    //!< Decimal stream (e.g., IPv4 address).
    TMSTAT_T_HEX        = 6,    //!< Hexadecimal stream (e.g., MAC address).
};

/**
 * Merge rules.
 */
enum tmstat_rule {
    TMSTAT_R_KEY        = 0,    //!< This column stores row identity.
    TMSTAT_R_OR         = 1,    //!< Logical or (useful for bit sets).
    TMSTAT_R_SUM        = 2,    //!< Sum fields.
    TMSTAT_R_MIN        = 3,    //!< Select smallest.
    TMSTAT_R_MAX        = 4,    //!< Select largest.
};

enum tmstat_merge { 
    TMSTAT_MERGE_PUBLIC = 0,    //!< Merge only public tables
    TMSTAT_MERGE_ALL    = 1,    //!< Include internal tables
};

/**
 * Column descriptor.
 */
struct TMCOL {
#ifdef __cplusplus
    TMCOL() { }
    TMCOL(char *_name, unsigned _size, unsigned _offset) {
        name = _name;
        size = _size;
        offset = _offset;
        type = TMSTAT_T_UNSIGNED;
        rule = TMSTAT_R_KEY;
    }
    TMCOL(char *_name, unsigned _size, unsigned _offset,
          enum tmstat_type _type) {
        name = _name;
        size = _size;
        offset = _offset;
        type = _type;
        rule = TMSTAT_R_KEY;
    }
    TMCOL(char *_name, unsigned _size, unsigned _offset,
          enum tmstat_type _type, enum tmstat_rule _rule) {
        name = _name;
        size = _size;
        offset = _offset;
        type = _type;
        rule = _rule;
    }
#endif
    char                *name;          //!< Column name.
    unsigned            size;           //!< Column size.
    unsigned            offset;         //!< Column offset.
    enum tmstat_type    type;           //!< Data type.
    enum tmstat_rule    rule;           //!< Merge rule.
};

/**
 * Column descriptor convenience macros.
 *
 * These macros allow you to easily describe fields contained within
 * a struct.
 */
#ifdef __cplusplus
#define TMCOL_FIELD(STRUCT, FIELD, X...) TMCOL(                             \
    /* name */    #FIELD,                                                   \
    /* size */    sizeof(((STRUCT *)0)->FIELD),                             \
    /* offset */  (unsigned)(unsigned long)(&((STRUCT *)0)->FIELD),         \
    /* options */ ##X                                                       \
)
#define TMCOL_NAMED_FIELD(STRUCT, NAME, FIELD, X...) TMCOL(                 \
    /* name */    #NAME,                                                    \
    /* size */    sizeof(((STRUCT *)0)->FIELD),                             \
    /* offset */  (unsigned)(unsigned long)(&((STRUCT *)0)->FIELD),         \
    /* options */ ##X                                                       \
)
#define TMCOL_INT(S, F, X...)  TMCOL_FIELD(S, F, TMSTAT_T_SIGNED, ##X)
#define TMCOL_UINT(S, F, X...) TMCOL_FIELD(S, F, TMSTAT_T_UNSIGNED, ##X)
#define TMCOL_TEXT(S, F, X...) TMCOL_FIELD(S, F, TMSTAT_T_TEXT, ##X)
#define TMCOL_BIN(S, F, X...)  TMCOL_FIELD(S, F, TMSTAT_T_BIN, ##X)
#define TMCOL_DEC(S, F, X...)  TMCOL_FIELD(S, F, TMSTAT_T_DEC, ##X)
#define TMCOL_HEX(S, F, X...)  TMCOL_FIELD(S, F, TMSTAT_T_HEX, ##X)
#define TMCOL_NAMED_INT(S, N, F, X...)                                     \
    TMCOL_NAMED_FIELD(S, N, F, TMSTAT_T_SIGNED, ##X)
#define TMCOL_NAMED_UINT(S, N, F, X...)                                    \
    TMCOL_NAMED_FIELD(S, N, F, TMSTAT_T_UNSIGNED, ##X)
#define TMCOL_NAMED_TEXT(S, N, F, X...)                                    \
    TMCOL_NAMED_FIELD(S, N, F, TMSTAT_T_TEXT, ##X)
#define TMCOL_NAMED_BIN(S, N, F, X...)                                     \
    TMCOL_NAMED_FIELD(S, N, F, TMSTAT_T_BIN, ##X)
#define TMCOL_NAMED_DEC(S, N, F, X...)                                     \
    TMCOL_NAMED_FIELD(S, N, F, TMSTAT_T_DEC, ##X)
#define TMCOL_NAMED_HEX(S, N, F, X...)                                     \
    TMCOL_NAMED_FIELD(S, N, F, TMSTAT_T_HEX, ##X)
#else
#define TMCOL_FIELD(STRUCT, FIELD, ...) {                                   \
    .name = #FIELD,                                                         \
    .size = sizeof(((STRUCT *)0)->FIELD),                                   \
    .offset = (unsigned)(unsigned long)(&((STRUCT *)0)->FIELD),             \
    __VA_ARGS__                                                             \
}
#define TMCOL_NAMED_FIELD(STRUCT, NAME, FIELD, ...) { \
    .name = #NAME,                                                          \
    .size = sizeof(((STRUCT *)0)->FIELD),                                   \
    .offset = (unsigned)(unsigned long)(&((STRUCT *)0)->FIELD),             \
    __VA_ARGS__                                                             \
}
#define TMCOL_INT(S, F, ...)                                                \
    TMCOL_FIELD(S, F, .type = TMSTAT_T_SIGNED, __VA_ARGS__)
#define TMCOL_UINT(S, F, ...)                                               \
    TMCOL_FIELD(S, F, .type = TMSTAT_T_UNSIGNED, __VA_ARGS__)
#define TMCOL_TEXT(S, F, ...)                                               \
    TMCOL_FIELD(S, F, .type = TMSTAT_T_TEXT, __VA_ARGS__)
#define TMCOL_BIN(S, F, ...)                                                \
    TMCOL_FIELD(S, F, .type = TMSTAT_T_BIN, __VA_ARGS__)
#define TMCOL_DEC(S, F, ...)                                                \
    TMCOL_FIELD(S, F, .type = TMSTAT_T_DEC, __VA_ARGS__)
#define TMCOL_HEX(S, F, ...)                                                \
    TMCOL_FIELD(S, F, .type = TMSTAT_T_HEX, __VA_ARGS__)

#define TMCOL_NAMED_INT(S, N, F, ...)                                      \
    TMCOL_NAMED_FIELD(S, N, F, .type = TMSTAT_T_SIGNED, __VA_ARGS__)
#define TMCOL_NAMED_UINT(S, N, F, ...)                                     \
    TMCOL_NAMED_FIELD(S, N, F, .type = TMSTAT_T_UNSIGNED, __VA_ARGS__)
#define TMCOL_NAMED_TEXT(S, N, F, ...)                                     \
    TMCOL_NAMED_FIELD(S, N, F, .type = TMSTAT_T_TEXT, __VA_ARGS__)
#define TMCOL_NAMED_BIN(S, N, F, ...)                                      \
    TMCOL_NAMED_FIELD(S, N, F, .type = TMSTAT_T_BIN, __VA_ARGS__)
#define TMCOL_NAMED_DEC(S, N, F, ...)                                      \
    TMCOL_NAMED_FIELD(S, N, F, .type = TMSTAT_T_DEC, __VA_ARGS__)
#define TMCOL_NAMED_HEX(S, N, F, ...)                                      \
    TMCOL_NAMED_FIELD(S, N, F, .type = TMSTAT_T_HEX, __VA_ARGS__)
#endif

/**
 * Create segment.
 *
 * This creates a new segment which may be used to store values, however the
 * segment is not visible to others until it is published.  This two-stage
 * process allows an upcoming process to construct an valid segment before it
 * makes it visible to others (or overwrites the segment published by a
 * previous run).
 *
 * If name is NULL, a private anonymous segment is created.  This segment
 * may never be published (as it does not have a backing file).  Such a
 * segment is useful for segments that are used to store intermediate results
 * (such as with union segments, internally).
 *
 * Note that name must be a valid for a file.  We further restrict segment
 * names to lower-case letters, underscore ('_'), dot ('.'), and dash ('-').
 * 
 * That is, the regexp [a-z][a-z0-9_.-]*
 *
 * @param[out]  stat        New segment handle.
 * @param[in]   name        Segment name (e.g., program name), or NULL.
 * @return 0 on success, -1 on failure.
 */
int tmstat_create(TMSTAT *stat, char *name);

/**
 * Publish segment.
 *
 * This makes a new segment visible to consumers.  The segment will replace
 * any previously-existing segment with the same name.  This allows a new
 * invocation of a daemon to atomically update the old segment with a new
 * valid segment.
 *
 * Segments may not be published multiple times.
 *
 * Unless you have a particular directory in mind, use TMSTAT_DIR_PUBLISH.
 *
 * @param[in]   stat        Segment to publish.
 * @param[in]   directory   Directory name.
 * @return 0 on success, -1 on failure.
 */
int tmstat_publish(TMSTAT stat, char *directory);

/**
 * Destroy segment.
 *
 * If the segment is published, it will be removed from its directory.
 *
 * Note that all memory associated with the segment will be freed, meaning
 * that any pointers remaining into allocated rows or TMTABLE handles will be
 * invalid.
 *
 * @param[in]   stat        Segment to destroy.
 */
void tmstat_destroy(TMSTAT stat);

/**
 * Remove the backing file for a stat segment.  It is an error to call
 * this for union segments or other read-only segments.  The in-process
 * resources will not be freed, so the segment can continue to be used
 * after unlink until it is deallocated.
 *
 * @param[in]   stat        Segment to unlink.
 * @return 0 on success, -1 on failure.
 */
int tmstat_unlink(TMSTAT stat);

/**
 * Free the in-process resources associated with a stat segment
 * without unlinking the backing file.
 *
 * Note that all memory associated with the segment will be freed, meaning
 * that any pointers remaining into allocated rows or TMTABLE handles will be
 * invalid.
 *
 * @param[in]   stat        Segment to deallocate.
 */
void tmstat_dealloc(TMSTAT stat);

/**
 * Make a handle which refers to the union of multiple segments.
 *
 * This handle may be used to view multiple segments as if they were
 * one segment.  When lookups are performed, the children handles are
 * queried and a merged result set is returned.
 *
 * @param[out]  stat        New union handle.
 * @param[in]   children    Child handles.
 * @param[in]   count       Number of handles in children.
 * @return 0 on success, -1 on failure.
 */
int tmstat_union(TMSTAT *stat, TMSTAT *children, unsigned count);

/**
 * Subscribe to directory.
 *
 * This produces a union handle which contains all segments currently
 * published in the specified directory.  This will not include segments
 * published after this handle is created (including new versions of
 * existing segments published later).  It is important to resubscribe
 * occasionally to pick up new arrivals.
 *
 * Unless you have a particular directory in mind, use TMSTAT_DIR_SUBSCRIBE.
 *
 * @param[out]  stat        New union handle.
 * @param[in]   directory   Directory name.
 * @return 0 on success, -1 on failure.
 */
int tmstat_subscribe(TMSTAT *stat, char *directory);

/**
 * Extract tmstat segments from a specific file.
 *
 * This is useful during system diagnosis, and is not intended for regular
 * consumption.
 *
 * @param[in]   path        Path to file to inspect.
 * @param[in]   dirname     Directory name to write segment files into.
 * @return 0 on success, -1 on failure.
 */
int tmstat_extract(const char *path, const char *dirname);

/**
 * Read segment from a specific file.
 *
 * This is useful during system diagnosis, and is not intended for regular
 * consumption.  If the file specified is private (i.e., unpublished),
 * the results of queries may be incomplete.
 *
 * @param[out]  stat        New union handle.
 * @param[in]   path        Path to file to inspect.
 * @return 0 on success, -1 on failure.
 */
int tmstat_read(TMSTAT *stat, char *path);

/**
 * Reread data if possible and appropriate.  If force is true, the
 * data will be reread even if they appear to be up-to-date.
 * If this fails, it does so silently and leaves stat untouched.
 * Presently, this has no effect on any stat handle not created via
 * tmstat_subscribe.  Note that this happens automatically prior to
 * the execution of a query.
 *
 * @param[in]   stat        Stat handle to refresh.
 * @param[in]   force       Force refresh?
 */
void tmstat_refresh(TMSTAT stat, int force);

/**
 * Register table.
 *
 * This adds a new table which initially contains no rows.  Once the table is
 * registered, rows may be added to it.
 *
 * Note that table names have some character-set restrictions: the leading
 * character must be alphabetic, followed by alphanumeric, underscore ('_'),
 * or slash ('/').  Only lower case is allowed.
 *
 * Column names are similarly limited, but instead of slash ('/'), dot
 * ('.') is allowed and a digit is allowed in the first character.
 *
 * That is, the regular expressions for names are:
 *
 *      table name    ::= [a-z][a-z0-9_/]*
 *      column name   ::= [a-z0-9][a-z0-9_.]*
 *
 * These restrictions are in place to facilitate the development of
 * expression parsers that may easily describe segment fields.
 *
 * By convention, if name contains a slash ('/') character, it is assumed
 * to be an "internal" table.  Such tables are considered informal, and
 * not normally included when constructing rollup segments.  This provides
 * a clear idea of what stats are "offical" -- are part of the interface
 * contract made by the producer.  In contrast, internal tables are for
 * internal use (e.g., debugging), and may change or be removed at any
 * time.  Such tables are typically named in the form of "producer/table"
 * (e.g., "proc/device"), so that their names will not conflict with the
 * tables registered by other producers.
 *
 * Column descriptors need not be ordered by their offsets into the
 * row.  Additionally, rowsz need not equal the sum of the columns'
 * sizes, provided that rowsz is the greater of the two.  The space
 * allocated for each row will be rowsz; space not covered by a column
 * definition is ignored by the library.  In particular, it won't be
 * modified for an allocated row and the contents of space not covered
 * by a column definition in a row that is the result of a merge is
 * undefined.
 *
 * Zero-sized columns and overlapping columns are disallowed.
 *
 * @param[in]   stat        Segment to store table in.
 * @param[out]  table       New table handle.
 * @param[in]   name        Table name.
 * @param[in]   cols        Column descriptors.
 * @param[in]   count       Total descriptors in cols.
 * @param[in]   rowsz       Size in bytes of a row.
 * @return 0 on success, -1 on failure.
 */
int tmstat_table_register(TMSTAT stat, TMTABLE *table, char *name,
        struct TMCOL *cols, unsigned count, unsigned rowsz);

/**
 * Obtain the column metadata for a table.
 *
 * If no table exists with that name, 0 columns are returned (i.e., it is
 * treated as if that table is empty).
 *
 * Note that column information is returned in the same order it is
 * given to tmstat_table_register and is thus not necessarily ordered
 * by offset.  Note also that the information in cols is not
 * necessarily sufficient to determine the row size, as it may be
 * greater than that the sum of the columns' sizes.
 *
 * @param[in]   stat        Associated segment.
 * @param[in]   table_name  Table name to search for.
 * @param[out]  cols        Pointer to column descriptor array.
 * @param[out]  col_count   Number of columns present.
 */
void tmstat_table_info(TMSTAT stat, char *table_name,
        struct TMCOL **cols, unsigned *col_count);

int tmstat_is_table_sorted(TMSTAT stat, char *table_name);

/**
 * Obtain the row size for a table.
 *
 * If no table exists with that name, 0 is returned (i.e., it is
 * treated as if that table is empty).
 *
 * As allowed by tmstat_table_register, this value may not be the sum
 * of the table's columns' sizes.
 *
 * @param[in]   stat        Associated segment.
 * @param[in]   table_name  Table name to search for.
 * @param[out]  rowsz       Row size.
 */
void tmstat_table_row_size(TMSTAT stat, char *table_name, unsigned *rowsz);

/**
 * Obtain a table's name.
 *
 * @param[in]   table       Associated table.
 * @return table name.
 */
char *tmstat_table_name(TMTABLE table);

/**
 * Create a new row.  Newly created rows are guaranteed to be zeroed out.
 * The reference count for the row returned will be 1.  If the
 * reference count falls to zero, the row will be removed from the
 * table.  If you wish for the row to persist in the table beyond the
 * lifetime of the TMROW object, call tmstat_row_preserve.
 *
 * @param[in]   stat        Associated segment.
 * @param[in]   table       Table to create row for.
 * @param[out]  row         New row handle.
 * @return 0 on success, -1 on failure.
 */
int tmstat_row_create(TMSTAT stat, TMTABLE table, TMROW *row);

/**
 * Create n new rows.  Equivalent to but more efficient than n calls
 * to tmstat_Row_create.
 *
 * @param[in]   stat        Associated segment.
 * @param[in]   table       Table to create row for.
 * @param[out]  row         Array of n handles for new rows.
 * @param[in]   n           Number of rows to create.
 * @return 0 on success, -1 on failure.
 */
int tmstat_row_create_n(TMSTAT stat, TMTABLE table, TMROW *row, unsigned n);

/**
 * Cause a row not to be removed from its table when it is deallocated.
 * This has no effect on rows not obtaied via tmstat_row_create or
 * rows that have already been passed to this function.
 *
 * @param[in]   row         Row to preserve.
 */
void tmstat_row_preserve(TMROW row);

/**
 * Obtain extra reference to a row.
 *
 * @param[in]  row          Row handle.
 * @return row itself (so that new_ref = tmstat_row_ref(old_ref) works).
 */
TMROW tmstat_row_ref(TMROW row);

/**
 * Drop reference to a row.
 *
 * If this is the last reference to the row, it is destroyed.
 *
 * @param[in]  row          Row handle.
 * @return NULL.
 */
TMROW tmstat_row_drop(TMROW row);

/**
 * Obtain metainformation for a row.
 *
 * @param[in]   row         The row handle of interest.
 * @param[out]  col         The row's column definitions.
 * @param[out]  col_count   The number of columns in the row.
 */
void tmstat_row_description(TMROW row, TMCOL *col, unsigned *col_count);

/**
 * Locate field within row.
 *
 * Fields are stored contiguously.  Requesting the first column will give you
 * a pointer to the beginning of the field structure.
 *
 * Be careful when assuming which fields lie where.  Unless you created a
 * table, it may contain any number of fields that will surprise you.  If you
 * are consuming a row, use the field lookups to provide a map rather than
 * assuming that it will fit with the structure used by your version of your
 * client -- these things may change in one of the producers in the future.
 *
 * Passing NULL for name will place the base address of the row in p.
 * Note that this will be different than requesting the first field of the
 * row if the first field does not begin at offset 0.
 *
 * @param[in]   row         Row handle.
 * @param[in]   name        Field name or NULL for base address of row.
 * @param[out]  p           Pointer to field.
 * @return 0 on success, -1 on failure.
 */
int tmstat_row_field(TMROW row, char *name, void *p);

/**
 * Return row's field's signed value.
 *
 * Returns an unsigned representation of the named field's value, or 0 if
 * either the field's type is not representable as a number or does not
 * exist.
 *
 * @param[in]   row         Row handle.
 * @param[in]   name        Field name.
 * @return field value, or 0 if none.
 */
signed long long tmstat_row_field_signed(TMROW row, char *name);

/**
 * Return row's field's unsigned value.
 *
 * Returns an unsigned representation of the named field's value, or 0 if
 * either the field's type is not representable as a number or does not
 * exist.
 *
 * @param[in]   row         Row handle.
 * @param[in]   name        Field name.
 * @return field value, or 0 if none.
 */
unsigned long long tmstat_row_field_unsigned(TMROW row, char *name);

/**
 * Obtain the column metadata for row.
 *
 * @param[in]   row         Associated row.
 * @param[out]  cols        Pointer to column descriptor array.
 * @param[out]  col_count   Number of columns present.
 */
void tmstat_row_info(TMROW row, struct TMCOL **cols, unsigned *col_count);

/**
 * Obtain the name of the table from which a row came.
 * @param[in]   row         Associated row.
 * @return table name.
 */
const char *tmstat_row_table(TMROW row);

/**
 * Locate rows by column values.
 *
 * This function returns handles to any rows in the table that contain columns
 * with the requested values.  This mechanism allows for row lookup by key.
 *
 * If all the TMSTAT_R_KEY columns for a table are specified, and no other
 * columns are specified, and the table belongs to a merged segment that has
 * been sorted, the query will be accelerated.
 *
 * Note that an empty match set (col_count is 0) selects all rows.
 *
 * If row_handles is NULL, no rows will be returned and only the match_count
 * will be updated; otherwise, an array large enough to store the matching
 * row set will be allocated and returned in row_handles.  If row_handles is
 * not NULL, you must tmstat_row_drop each of the rows returned.
 *
 * @param[in]   stat        Segment to search.
 * @param[in]   table_name  Table name to search for.
 * @param[in]   col_count   Number of columns to key on.
 * @param[in]   col_names   Column names to key upon.
 * @param[in]   col_values  Column values to match.
 * @param[out]  row_handles Array containing result rows.
 * @param[out]  match_count Number of matching rows.
 * @return 0 on success, -1 on failure.
 */
int tmstat_query(TMSTAT stat, char *table_name,
        unsigned col_count, char **col_names, void **col_values,
        TMROW **row_handles, unsigned *match_count);

/**
 * Locate rows by column values and perform rollup (merge).
 *
 * This function returns a handle to 1 row that contains the 
 * rolled up (merged) values for the rows in the table that contains 
 * columns with the requested values.  
 * This mechanism allows for row lookup by key(s).
 *
 * All columns specified must be key values (TMSTAT_R_KEY).
 *
 * Note that an empty match set (col_count is 0) selects all rows and 
 * performs a merge(rollup) on all rows in the table.
 *
 * A row will be allocated and returned in row_handle.
 *
 * @param[in]   stat        Segment to search.
 * @param[in]   table_name  Table name to search for.
 * @param[in]   col_count   Number of columns to key on.
 * @param[in]   col_names   Column names to key upon.
 * @param[in]   col_values  Column values to match.
 * @param[out]  row_handle  A row containing result or NULL if none.
 * @return 0 on success, -1 on failure.
 */
int tmstat_query_rollup(TMSTAT stat, char *table_name,
        unsigned col_count, char **col_names, void **col_values,
        TMROW *row_handle);


/**
 * Merge all tables into one segment file.
 *
 * @param[in]   stat        Source segment.
 * @param[in]   path        Path to output file.
 * @param[in]   merge       Only public tables or all.
 * @return 0 on success, -1 on failure.
 */
int tmstat_merge(TMSTAT stat, char *path, enum tmstat_merge merge);

/**
 * Merge 2 rows. Rows are assumed to be from same table. Values
 * in the "src_row" are added to the values in the "dst_row".
 *
 * @param[in]   dst_row     Destination row. 
 * @param[in]   src_row     The source row.
 * @return 0 on success, -1 on failure.
 */
int tmstat_merge_row(TMROW dst_row, TMROW src_row);

/**
 * Create expression evaluation context.
 *
 * @param[out]  eval        Evaluation context.
 * @return on success, -1 on failure.
 */
int tmstat_eval_create(TMSTAT_EVAL *eval);

/**
 * Destroy expression evaluation context.
 *
 * @param[in]   eval        Evaluation context to destroy.
 */
void tmstat_eval_destroy(TMSTAT_EVAL eval);

/**
 * Evaluate expression.
 *
 * @param[in]   eval        Evaluation context.
 * @param[in]   stat        Source segment.
 * @param[in]   expr        Expression to evaluate.
 * @param[out]  result      Expression result (or NULL upon error).
 *                                       User must free.
 * @param[out]  errstr      Error description (optional).
 * @param[out]  erridx      Error position (optional).
 * @return 0 on success, -1 on failure.
 */
int tmstat_eval(TMSTAT_EVAL eval, TMSTAT stat, const char *expr,
    char **result, char **errstr, unsigned *erridx);

/**
 * Evaluate expression as a signed integer.
 *
 * @param[in]   eval        Evaluation context.
 * @param[in]   stat        Source segment.
 * @param[in]   expr        Expression to evaluate.
 * @param[out]  result      Expression result (or NULL upon error).
 * @param[out]  errstr      Error description (optional).
 * @param[out]  erridx      Error position (optional).
 * @return 0 on success, -1 on failure.
 */
int tmstat_eval_signed(TMSTAT_EVAL eval, TMSTAT stat, const char *expr,
    signed long long *result, char **errstr, unsigned *erridx);

/**
 * Parse the standard tmstat representation of a value.  Presently,
 * this works only for bin, dec, and hex field types.  The output
 * buffer must be long enough to hold the result.
 *
 * @param[in]   in          Input string.
 * @param[out]  endp        If not NULL, set to the first invalid character
 *                          found in the input.
 * @param[out]  out         Output buffer (\a size bytes).
 * @param[in]   type        The type of the field.
 * @param[in]   size        The size of the field.
 * @return 0 on success, -1 if invalid characters were encountered,
 * the string was too short or too long, or an unsupported type was
 * passed.
 */
int tmstat_parse(const char *in, char **endp, void *out,
                 enum tmstat_type type, unsigned size);

/**
 * Print a value in the standard tmstat string notation.  Presently,
 * this works only for bin, dec, and hex field types.  The result is
 * null-terminated.  The output buffer must be large enough to hold
 * the result.
 *
 * @param[in]   in          Input value.
 * @param[out]  out         Output buffer.
 * @param[in]   type        The type of the field.
 * @param[in]   size        The size of the field.
 * @return 0 on success, -1 if an unsupported type was passed.
 */
int tmstat_print(void *in, char *out, enum tmstat_type type, unsigned size);

/**
 * Return the size of buffer required to hold the standard tmstat string
 * representation for any value of a field of given type and size.
 */
unsigned tmstat_strlen(enum tmstat_type type, unsigned size);

#ifdef __cplusplus
}
#endif

#endif /* __TMSTAT_TMSTAT_H__ */