DragonFly On-Line Manual Pages

MTBL_MERGER(3)                                                  MTBL_MERGER(3)

NAME
       mtbl_merger - merge multiple MTBL data sources into a single output

SYNOPSIS
       #include <mtbl.h>

       Merger objects:

       struct mtbl_merger *
       mtbl_merger_init(const struct mtbl_merger_options *mopt);

       void
       mtbl_merger_destroy(struct mtbl_merger **m);

       void
       mtbl_merger_add_source(struct mtbl_merger *m, const struct mtbl_source *s);

       const struct mtbl_source *
       mtbl_merger_source(struct mtbl_merger *m);

       Merger options:

       struct mtbl_merger_options *
       mtbl_merger_options_init(void);

       void
       mtbl_merger_options_destroy(struct mtbl_merger_options **mopt);

       void
       mtbl_merger_options_set_merge_func(
               struct mtbl_merger_options *mopt,
               mtbl_merge_func fp,
               void *clos);

       typedef void
       (*mtbl_merge_func)(void *clos,
               const uint8_t *key, size_t len_key,
               const uint8_t *val0, size_t len_val0,
               const uint8_t *val1, size_t len_val1,
               uint8_t **merged_val, size_t *len_merged_val);

DESCRIPTION
       Multiple MTBL data sources may be merged together using the mtbl_merger
       interface, which reads key-value entries from one or more sources and
       provides these entries in sorted order. The sorted entries may be
       consumed via the mtbl_source(3) and mtbl_iter(3) interfaces.

       Because the MTBL format does not allow duplicate keys, the caller must
       provide a function which will accept a key and two conflicting values
       for that key and return a replacement value. This function may be
       called multiple times for the same key if more than two sources are
       being merged.

       mtbl_merger objects are created with the mtbl_merger_init() function,
       which requires a non-NULL mopt argument which has been configured with
       a merge function fp.

       One or more mtbl_reader objects must be provided as input to the
       mtbl_merger object by calling mtbl_merger_add_source(). After the
       desired sources have been configured, mtbl_merger_source() should be
       called in order to consume the merged output via the mtbl_source(3)
       interface.

   Merger options
       merge_func

           This option specifies a merge function callback, consisting of a
           function pointer fp and a pointer to user data clos which will be
           passed as the first argument to fp. The merge function callback
           will be used during iteration over the mtbl_merger object to merge
           entries with duplicate keys in the input sources.

           The remaining arguments to the merge function are:

           key -- pointer to the key for which there exist duplicate values.

           len_key -- length of the key.

           val0 -- pointer to the first value.

           len_val_0 -- length of the first value.

           val1 -- pointer to the second value.

           len_val_1 -- length of the second value.

           merged_val -- pointer to where the callee should place its merged
           value.

           len_merged_val -- pointer to where the callee should place the
           length of its merged value.

           merged_val must be allocated with the system allocator, and the
           mtbl_merger interface takes responsibility for free()ing the value
           once it is no longer needed.

           The callee may provide an empty value as the merged value, in which
           case merged_val must still contain an allocated, non-NULL value and
           len_merged_val must contain the value 0.

           The callee may indicate an error by returning NULL in the
           merged_val argument, which will abort iteration over the
           mtbl_merger object.

RETURN VALUE
       If the merge function callback is unable to provide a merged value
       (that is, it fails to return a non-NULL value in its merged_val
       argument), the merge process will be aborted, and any iterators over
       the mtbl_merger object (via the mtbl_source(3) interface) will return
       mtbl_res_failure.

                                  01/31/2014                    MTBL_MERGER(3)