1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147
|
'\" t
.\" Title: mtbl_sorter
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\" Date: 01/31/2014
.\" Manual: \ \&
.\" Source: \ \&
.\" Language: English
.\"
.TH "MTBL_SORTER" "3" "01/31/2014" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * 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\&.
|