'\" t
.\"     Title: mtbl_sorter
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 05/29/2012
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "MTBL_SORTER" "3" "05/29/2012" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
mtbl_sorter \- sort a sequence of unordered key\-value pairs
.SH "SYNOPSIS"
.sp
\fB#include <mtbl\&.h>\fR
.sp
Sorter objects:
.sp
.nf
\fBstruct mtbl_sorter *
mtbl_sorter_init(const struct mtbl_sorter_options *\fR\fB\fIsopt\fR\fR\fB);\fR
.fi
.sp
.nf
\fBvoid
mtbl_sorter_destroy(struct mtbl_sorter **\fR\fB\fIs\fR\fR\fB);\fR
.fi
.sp
.nf
\fBmtbl_res
mtbl_sorter_add(struct mtbl_sorter *\fR\fB\fIs\fR\fR\fB,
        const uint8_t *\fR\fB\fIkey\fR\fR\fB, size_t \fR\fB\fIlen_key\fR\fR\fB,
        const uint8_t *\fR\fB\fIval\fR\fR\fB, size_t \fR\fB\fIlen_val\fR\fR\fB);\fR
.fi
.sp
.nf
\fBmtbl_res
mtbl_sorter_write(struct mtbl_sorter *\fR\fB\fIs\fR\fR\fB, struct mtbl_writer *\fR\fB\fIw\fR\fR\fB);\fR
.fi
.sp
.nf
\fBstruct mtbl_iter *
mtbl_sorter_iter(struct mtbl_sorter *\fR\fB\fIs\fR\fR\fB);\fR
.fi
.sp
Sorter options:
.sp
.nf
\fBstruct mtbl_sorter_options *
mtbl_sorter_options_init(void);\fR
.fi
.sp
.nf
\fBvoid
mtbl_sorter_options_destroy(struct mtbl_sorter_options **\fR\fB\fIsopt\fR\fR\fB);\fR
.fi
.sp
.nf
\fBvoid
mtbl_sorter_options_set_merge_func(
        struct mtbl_sorter_options *\fR\fB\fIsopt\fR\fR\fB,
        mtbl_merge_func \fR\fB\fIfp\fR\fR\fB,
        void *\fR\fB\fIclos\fR\fR\fB);\fR
.fi
.sp
.nf
\fBvoid
mtbl_sorter_options_set_temp_dir(
        struct mtbl_sorter_options *\fR\fB\fIsopt\fR\fR\fB,
        const char *\fR\fB\fItemp_dir\fR\fR\fB);\fR
.fi
.sp
.nf
\fBvoid
mtbl_sorter_options_set_max_memory(
        struct mtbl_sorter_options *\fR\fB\fIsopt\fR\fR\fB,
        size_t \fR\fB\fImax_memory\fR\fR\fB);\fR
.fi
.SH "DESCRIPTION"
.sp
The \fBmtbl_sorter\fR 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 \fBmtbl_iter\fR interface using the \fBmtbl_sorter_iter\fR() function, or they may be dumped to an \fBmtbl_writer\fR object using the \fBmtbl_sorter_write\fR() function\&. The \fBmtbl_sorter\fR 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, \fBmtbl_sorter\fR(3) is an "external sorting" implementation\&.)
.sp
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 \fBmtbl_merger\fR(3) for further details about the merge function\&.
.sp
\fBmtbl_sorter\fR objects are created with the \fBmtbl_sorter_init\fR() function, which requires a non\-NULL \fIsopt\fR argument which has been configured with a merge function \fIfp\fR\&.
.sp
\fBmtbl_sorter_add\fR() copies key\-value pairs from the caller into the \fBmtbl_sorter\fR object\&. Keys are specified as a pointer to a buffer, \fIkey\fR, and the length of that buffer, \fIlen_key\fR\&. Values are specified as a pointer to a buffer, \fIval\fR, and the length of that buffer, \fIlen_val\fR\&.
.sp
Once the caller has finished adding entries to the \fBmtbl_sorter\fR object, either \fBmtbl_sorter_write\fR() or \fBmtbl_sorter_iter\fR() should be called in order to consume the sorted output\&. It is a runtime error to call \fBmtbl_sorter_add\fR() on an \fBmtbl_sorter\fR 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 \fBmtbl_sorter_destroy\fR() on the depleted \fBmtbl_sorter\fR object\&.
.SS "Sorter options"
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBtemp_dir\fR
.RS 4
.sp
Specifies the temporary directory to use\&. Defaults to /var/tmp\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBmax_memory\fR
.RS 4
.sp
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\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBmerge_func\fR
.RS 4
.sp
See \fBmtbl_merger\fR(3)\&. An \fBmtbl_merger\fR object is used internally for the external sort\&.
.RE
.SH "RETURN VALUE"
.sp
If the merge function callback is unable to provide a merged value (that is, it fails to return a non\-NULL value in its \fImerged_val\fR argument), the sort process will be aborted, and \fBmtbl_sorter_write\fR() or \fBmtbl_iter_next\fR() will return \fBmtbl_res_failure\fR\&.
.sp
\fBmtbl_sorter_write\fR() returns \fBmtbl_res_success\fR if the sorted output was successfully written, and \fBmtbl_res_failure\fR otherwise\&.