mtbl_merger(3) [debian man page]

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)

MTBL_SORTER(3)															    MTBL_SORTER(3)

NAME

       mtbl_sorter - sort a sequence of unordered key-value pairs

SYNOPSIS

       #include <mtbl.h>

       Sorter objects:

       struct mtbl_sorter *
       mtbl_sorter_init(const struct mtbl_sorter_options *sopt);

       void
       mtbl_sorter_destroy(struct mtbl_sorter **s);

       mtbl_res
       mtbl_sorter_add(struct mtbl_sorter *s,
	       const uint8_t *key, size_t len_key,
	       const uint8_t *val, size_t len_val);

       mtbl_res
       mtbl_sorter_write(struct mtbl_sorter *s, struct mtbl_writer *w);

       struct mtbl_iter *
       mtbl_sorter_iter(struct mtbl_sorter *s);

       Sorter options:

       struct mtbl_sorter_options *
       mtbl_sorter_options_init(void);

       void
       mtbl_sorter_options_destroy(struct mtbl_sorter_options **sopt);

       void
       mtbl_sorter_options_set_merge_func(
	       struct mtbl_sorter_options *sopt,
	       mtbl_merge_func fp,
	       void *clos);

       void
       mtbl_sorter_options_set_temp_dir(
	       struct mtbl_sorter_options *sopt,
	       const char *temp_dir);

       void
       mtbl_sorter_options_set_max_memory(
	       struct mtbl_sorter_options *sopt,
	       size_t max_memory);

DESCRIPTION

       The mtbl_sorter interface accepts a sequence of key-value pairs with keys in arbitrary order and provides these entries in sorted order.
       The sorted entries may be consumed via the mtbl_iter interface using the mtbl_sorter_iter() function, or they may be dumped to an
       mtbl_writer object using the mtbl_sorter_write() function. The mtbl_sorter implementation buffers entries in memory up to a configurable
       limit before sorting them and writing them to disk in chunks. When the caller has finishing adding entries and requests the sorted output,
       entries from these sorted chunks are then read back and merged. (Thus, mtbl_sorter(3) is an "external sorting" implementation.)

       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_sorter objects are created with the mtbl_sorter_init() function, which requires a non-NULL sopt argument which has been configured
       with a merge function fp.

       mtbl_sorter_add() copies key-value pairs from the caller into the mtbl_sorter object. Keys are specified as a pointer to a buffer, key, and
       the length of that buffer, len_key. Values are specified as a pointer to a buffer, val, and the length of that buffer, len_val.

       Once the caller has finished adding entries to the mtbl_sorter object, either mtbl_sorter_write() or mtbl_sorter_iter() should be called in
       order to consume the sorted output. It is a runtime error to call mtbl_sorter_add() on an mtbl_sorter object after iteration has begun, and
       once the sorted output has been consumed, it is also a runtime error to call any other function but mtbl_sorter_destroy() on the depleted
       mtbl_sorter object.

   Sorter options
       temp_dir
	   Specifies the temporary directory to use. Defaults to /var/tmp.

       max_memory
	   Specifies the maximum amount of memory to use for in-memory sorting, in bytes. Defaults to 1 Gigabyte. This specifies a limit on the
	   total number of bytes allocated for key-value entries and does not include any allocation overhead.

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

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 sort process will be aborted, and mtbl_sorter_write() or mtbl_iter_next() will return mtbl_res_failure.

       mtbl_sorter_write() returns mtbl_res_success if the sorted output was successfully written, and mtbl_res_failure otherwise.

								    05/29/2012							    MTBL_SORTER(3)