deimos.leveldb.leveldb source code

1 /* Copyright (c) 2011 The LevelDB Authors. All rights reserved.
2   Use of this source code is governed by a BSD-style license that can be
3   found in the LICENSE file. See the AUTHORS file for names of contributors.
4 
5   C bindings for leveldb.  May be useful as a stable ABI that can be
6   used by programs that keep leveldb in a shared library, or for
7   a JNI api.
8 
9   Does not support:
10   . getters for the option types
11   . custom comparators that implement key shortening
12   . capturing post-write-snapshot
13   . custom iter, db, env, cache implementations using just the C bindings
14 
15   Some conventions:
16 
17   (1) We expose just opaque struct pointers and functions to clients.
18   This allows us to change internal representations without having to
19   recompile clients.
20 
21   (2) For simplicity, there is no equivalent to the Slice type.  Instead,
22   the caller has to pass the pointer and length as separate
23   arguments.
24 
25   (3) Errors are represented by a null-terminated c string.  NULL
26   means no error.  All operations that can raise an error are passed
27   a "char** errptr" as the last argument.  One of the following must
28   be true on entry:
29      *errptr == NULL
30      *errptr points to a malloc()ed null-terminated error message
31        (On Windows, *errptr must have been malloc()-ed by this library.)
32   On success, a leveldb routine leaves *errptr unchanged.
33   On failure, leveldb frees the old value of *errptr and
34   set *errptr to a malloc()ed error message.
35 
36   (4) Bools have the type ubyte (0 == false; rest == true)
37 
38   (5) All of the pointer arguments must be non-NULL.
39 */
40 
41 module deimos.leveldb.leveldb;
42 
43 private import std.stdint;
44 
45 public:
46 extern(C):
47 nothrow:
48 
49 /* Exported types */
50 alias void* leveldb_t;
51 alias void* leveldb_cache_t;
52 alias void* leveldb_comparator_t;
53 alias void* leveldb_env_t;
54 alias void* leveldb_filelock_t;
55 alias void* leveldb_filterpolicy_t;
56 alias void* leveldb_iterator_t;
57 alias void* leveldb_logger_t;
58 alias void* leveldb_options_t;
59 alias void* leveldb_randomfile_t;
60 alias void* leveldb_readoptions_t;
61 alias void* leveldb_seqfile_t;
62 alias void* leveldb_snapshot_t;
63 alias void* leveldb_writablefile_t;
64 alias void* leveldb_writebatch_t;
65 alias void* leveldb_writeoptions_t;
66 
67 /* DB operations */
68 
69 leveldb_t leveldb_open(
70     const leveldb_options_t options,
71     const char* name,
72     char** errptr);
73 
74 void leveldb_close(leveldb_t db);
75 
76 void leveldb_put(
77     leveldb_t db,
78     const leveldb_writeoptions_t options,
79     const char* key, size_t keylen,
80     const char* val, size_t vallen,
81     char** errptr);
82 
83 void leveldb_delete(
84     leveldb_t db,
85     const leveldb_writeoptions_t options,
86     const char* key, size_t keylen,
87     char** errptr);
88 
89 void leveldb_write(
90     leveldb_t db,
91     const leveldb_writeoptions_t options,
92     leveldb_writebatch_t batch,
93     char** errptr);
94 
95 /* Returns NULL if not found.  A malloc()ed array otherwise.
96    Stores the length of the array in *vallen. */
97 char* leveldb_get(
98     leveldb_t db,
99     const leveldb_readoptions_t options,
100     const char* key, size_t keylen,
101     size_t* vallen,
102     char** errptr);
103 
104 leveldb_iterator_t leveldb_create_iterator(
105     leveldb_t db,
106     const leveldb_readoptions_t options);
107 
108 const(leveldb_snapshot_t) leveldb_create_snapshot(
109     leveldb_t db);
110 
111 void leveldb_release_snapshot(
112     leveldb_t db,
113     const leveldb_snapshot_t snapshot);
114 
115 /* Returns NULL if property name is unknown.
116    Else returns a pointer to a malloc()-ed null-terminated value. */
117 char* leveldb_property_value(
118     leveldb_t db,
119     const char* propname);
120 
121 void leveldb_approximate_sizes(
122     leveldb_t db,
123     int num_ranges,
124     const const(char)* range_start_key, const size_t* range_start_key_len,
125     const const(char)* range_limit_key, const size_t* range_limit_key_len,
126     uint64_t* sizes);
127 
128 void leveldb_compact_range(
129     leveldb_t db,
130     const char* start_key, size_t start_key_len,
131     const char* limit_key, size_t limit_key_len);
132 
133 /* Management operations */
134 
135 void leveldb_destroy_db(
136     const leveldb_options_t options,
137     const char* name,
138     char** errptr);
139 
140 void leveldb_repair_db(
141     const leveldb_options_t options,
142     const char* name,
143     char** errptr);
144 
145 /* Iterator */
146 
147 void leveldb_iter_destroy(leveldb_iterator_t);
148 ubyte leveldb_iter_valid(const leveldb_iterator_t);
149 void leveldb_iter_seek_to_first(leveldb_iterator_t);
150 void leveldb_iter_seek_to_last(leveldb_iterator_t);
151 void leveldb_iter_seek(leveldb_iterator_t, const char* k, size_t klen);
152 void leveldb_iter_next(leveldb_iterator_t);
153 void leveldb_iter_prev(leveldb_iterator_t);
154 const(char*) leveldb_iter_key(const leveldb_iterator_t, size_t* klen);
155 const(char*) leveldb_iter_value(const leveldb_iterator_t, size_t* vlen);
156 void leveldb_iter_get_error(const leveldb_iterator_t, char** errptr);
157 
158 /* Write batch */
159 
160 leveldb_writebatch_t leveldb_writebatch_create();
161 void leveldb_writebatch_destroy(leveldb_writebatch_t);
162 void leveldb_writebatch_clear(leveldb_writebatch_t);
163 void leveldb_writebatch_put(
164     leveldb_writebatch_t,
165     const char* key, size_t klen,
166     const char* val, size_t vlen);
167 void leveldb_writebatch_delete(
168     leveldb_writebatch_t,
169     const char* key, size_t klen);
170 void leveldb_writebatch_iterate(
171     leveldb_writebatch_t,
172     void* state,
173     void function(void*, const char* k, size_t klen, const char* v, size_t vlen) put,
174     void function(void*, const char* k, size_t klen) deleted);
175 
176 /* Options */
177 
178 leveldb_options_t leveldb_options_create();
179 void leveldb_options_destroy(leveldb_options_t);
180 void leveldb_options_set_comparator(
181     leveldb_options_t,
182     leveldb_comparator_t);
183 void leveldb_options_set_filter_policy(
184     leveldb_options_t,
185     leveldb_filterpolicy_t);
186 void leveldb_options_set_create_if_missing(
187     leveldb_options_t, ubyte);
188 void leveldb_options_set_error_if_exists(
189     leveldb_options_t, ubyte);
190 void leveldb_options_set_paranoid_checks(
191     leveldb_options_t, ubyte);
192 void leveldb_options_set_env(leveldb_options_t, leveldb_env_t);
193 void leveldb_options_set_info_log(leveldb_options_t, leveldb_logger_t);
194 void leveldb_options_set_write_buffer_size(leveldb_options_t, size_t);
195 void leveldb_options_set_max_open_files(leveldb_options_t, int);
196 void leveldb_options_set_cache(leveldb_options_t, leveldb_cache_t);
197 void leveldb_options_set_block_size(leveldb_options_t, size_t);
198 void leveldb_options_set_block_restart_interval(leveldb_options_t, int);
199 
200 enum {
201   leveldb_no_compression = 0,
202   leveldb_snappy_compression = 1
203 }
204 void leveldb_options_set_compression(leveldb_options_t, int);
205 
206 /* Comparator */
207 
208 leveldb_comparator_t leveldb_comparator_create(
209     void* state,
210     void function(void*) destructor,
211     int function(
212         void*,
213         const char* a, size_t alen,
214         const char* b, size_t blen) compare,
215     const(char*) function(void*) name);
216 void leveldb_comparator_destroy(leveldb_comparator_t);
217 
218 /* Filter policy */
219 
220 leveldb_filterpolicy_t leveldb_filterpolicy_create(
221     void* state,
222     void function(void*) destructor,
223     char* function(
224         void*,
225         const const(char)* key_array, const size_t* key_length_array,
226         int num_keys,
227         size_t* filter_length) create_filter,
228     ubyte function(
229         void*,
230         const char* key, size_t length,
231         const char* filter, size_t filter_length) key_may_match,
232     const(char*) function(void*) name);
233 void leveldb_filterpolicy_destroy(leveldb_filterpolicy_t);
234 
235 leveldb_filterpolicy_t leveldb_filterpolicy_create_bloom(
236     int bits_per_key);
237 
238 /* Read options */
239 
240 leveldb_readoptions_t leveldb_readoptions_create();
241 void leveldb_readoptions_destroy(leveldb_readoptions_t);
242 void leveldb_readoptions_set_verify_checksums(
243     leveldb_readoptions_t,
244     ubyte);
245 void leveldb_readoptions_set_fill_cache(
246     leveldb_readoptions_t, ubyte);
247 void leveldb_readoptions_set_snapshot(
248     leveldb_readoptions_t,
249     const leveldb_snapshot_t);
250 
251 /* Write options */
252 
253 leveldb_writeoptions_t leveldb_writeoptions_create();
254 void leveldb_writeoptions_destroy(leveldb_writeoptions_t);
255 void leveldb_writeoptions_set_sync(
256     leveldb_writeoptions_t, ubyte);
257 
258 /* Cache */
259 
260 leveldb_cache_t leveldb_cache_create_lru(size_t capacity);
261 void leveldb_cache_destroy(leveldb_cache_t cache);
262 
263 /* Env */
264 
265 leveldb_env_t leveldb_create_default_env();
266 void leveldb_env_destroy(leveldb_env_t);
267 
268 /* Utility */
269 
270 /* Calls free(ptr).
271    REQUIRES: ptr was malloc()-ed and returned by one of the routines
272    in this file.  Note that in certain cases (typically on Windows), you
273    may need to call this routine instead of free(ptr) to dispose of
274    malloc()-ed memory returned by this library. */
275 void leveldb_free(void* ptr);
276 
277 /* Return the major version number for this release. */
278 int leveldb_major_version();
279 
280 /* Return the minor version number for this release. */
281 int leveldb_minor_version();
282