mtbl_fileset(3) [debian man page]

MTBL_FILESET(3) 														   MTBL_FILESET(3)

NAME

       mtbl_fileset - automatic multiple MTBL data file merger

SYNOPSIS

       #include <mtbl.h>

       Fileset objects:

       struct mtbl_fileset *
       mtbl_fileset_init(const char *fname, const struct mtbl_fileset_options *fopt);

       void
       mtbl_fileset_destroy(struct mtbl_fileset **f);

       void
       mtbl_fileset_reload(struct mtbl_fileset *f);

       const struct mtbl_source *
       mtbl_fileset_source(struct mtbl_fileset *f);

       Fileset options:

       struct mtbl_fileset_options *
       mtbl_fileset_options_init(void);

       void
       mtbl_fileset_options_destroy(struct mtbl_fileset_options **fopt);

       void
       mtbl_fileset_options_set_merge_func(
	       struct mtbl_fileset_options *fopt,
	       mtbl_merge_func fp,
	       void *clos);

       void
       mtbl_fileset_options_set_reload_frequency(
	       struct mtbl_fileset_options *fopt,
	       uint32_t reload_frequency);

DESCRIPTION

       The mtbl_fileset is a convenience interface for automatically maintaining a merged view of a set of MTBL data files. The merged entries may
       be consumed via the mtbl_source(3) and mtbl_iter(3) interfaces.

       mtbl_fileset objects are initialized from a "setfile", which specifies a list of filenames of MTBL data files, one per line. Internally, an
       mtbl_reader object is initialized from each filename and added to an mtbl_merger object. The setfile is watched for changes and the
       addition or removal of filenames from the setfile will result in the corresponding addition or removal of mtbl_reader objects.

       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 the same key is inserted
       more than twice. See mtbl_merger(3) for further details about the merge function.

       mtbl_fileset objects are created with the mtbl_fileset_init() function, which requires the path to a "setfile", fname, and a non-NULL fopt
       argument which has been configured with a merge function fp. mtbl_fileset_source() should then be called in order to consume output via the
       mtbl_source(3) interface.

       Accesses via the mtbl_source(3) interface will implicitly check for updates to the setfile. However, it may be necessary to explicitly call
       the mtbl_fileset_reload() function in order to check for updates, especially if files are being removed from the setfile.

   Fileset options
       merge_func
	   See mtbl_merger(3). An mtbl_merger object is used internally for the external sort.

       reload_interval
	   Specifies the interval between checks for updates to the setfile, in seconds. Defaults to 60 seconds.

								    05/29/2012							   MTBL_FILESET(3)

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.

								    05/29/2012							    MTBL_MERGER(3)