Permalink
Browse files

Added Edoc markup for types and functions.

  • Loading branch information...
1 parent ad7cd7c commit aca73990a7ce41dfca4de50b9a342b480d3a3750 @davisp davisp committed May 15, 2011
Showing with 256 additions and 17 deletions.
  1. +113 −3 include/erleveldb.hrl
  2. +143 −14 src/erleveldb.erl
View
116 include/erleveldb.hrl
@@ -1,28 +1,138 @@
-%% Opaque resource types
+%% This file is part of ErLevelDB released under the MIT license.
+%% See the LICENSE file for more information.
+
+%% @type db().
+%% An opaque handle to the database.
-type db() :: term().
+
+
+%% @type iterator().
+%% An opaque handle to a database iterator.
-type iterator() :: term().
+
+
+%% @type write_batch().
+%% An opaque handle to a write batch.
-type write_batch() :: term().
+
+
+%% @type snapshot().
+%% An opaque handle to a database snapshot.
-type snapshot() :: term().
-%% Database names and various options
+
+%% @type dbopts().
+%% Options for creating databases.
+%% <dl>
+%% <dt>create_if_missing</dt>
+%% <dd>
+%% Create the database if it doesn't exist.
+%% </dd>
+%% <dt>error_if_exists</dt>
+%% <dd>
+%% The database must not exist before creating it.
+%% </dd>
+%% <dt>paranoid_checks</dt>
+%% <dd>
+%% Instruct the database code to check extensively for
+%% corruption the the database files.
+%% </dd>
+%% <dt>{write_buffer_size, pos_integer()}</dt>
+%% <dd>
+%% The amount of RAM in bytes to use to buffer writes
+%% before they are sorted and written to disk. Up to 2x
+%% the <code>write_buffer_size</code> may be stored in
+%% RAM at one time. The default is 4MiB.
+%% </dd>
+%% <dt>{max_open_files, pos_integer()}</dt>
+%% <dd>
+%% The maximum number of files to keep open for accessing
+%% the database. The default is 100 open files.
+%% </dd>
+%% <dt>{cache_size, pos_integer()}</dt>
+%% <dd>
+%% The amount of RAM in bytes to use as a cache for
+%% frequently read data blocks. The default is 8MiB.
+%% </dd>
+%% <dt>{block_size, pos_integer()}</dt>
+%% <dd>
+%% The size of a data block when writing to disk. The
+%% default is 4KiB.
+%% </dd>
+%% <dt>{block_restart_interval, pos_integer()}</dt>
+%% <dd>
+%% The number of keys between restart points when delta
+%% encoding key prefixes. The default is 16. This option
+%% is usually left to the default.
+%% </dd>
+%% </dl>
-type dbopts() :: [
create_if_missing
| error_if_exists
| paranoid_checks
| {write_buffer_size, pos_integer()}
+ | {max_open_files, pos_integer()}
| {cache_size, pos_integer()}
| {block_size, pos_integer()}
| {block_restart_interval, pos_integer()}
].
+
+%% @type readopts().
+%% Options when issuing read requests.
+%% <dl>
+%% <dt>verify_checksums</dt>
+%% <dd>
+%% Verify the checksums for data read during this
+%% request.
+%% </dd>
+%% <dt>skip_cache</dt>
+%% <dd>
+%% Do not store data read into the block cache. This
+%% is mostly useful for bulk reads when you don't expect
+%% to reread the data quickly.
+%% </dd>
+%% <dt>{snapshot, snapshot()}</dt>
+%% <dd>
+%% A database snapshot to read from. This will only return
+%% results that existed at a given state of the database.
+%% </dd>
+%% </dl>
-type readopts() :: [
verify_checksums
| skip_cache
| {snapshot, snapshot()}
].
+
+%% @type writeopts().
+%% Options when issuing write requests.
+%% <dl>
+%% <dt>sync</dt>
+%% <dd>
+%% Call <code>fsync(2)</code> after the write
+%% operation to flush the operating system buffers
+%% to disk.
+%% </dd>
+%% <dt>snapshot</dt>
+%% <dd>
+%% Returns <code>{ok, snapshot()}</code> where the
+%% snapshot refers to a logical point in time just
+%% after this write complete but before any other
+%% modification to the database.
+%% </dd>
+%% </dl>
-type writeopts() :: [sync | snapshot].
-%% Misc
+
+%% @type seek_dest().
+%% Iterators can seek to a provided key to start iterating
+%% from. The two atoms <code>first</code> and
+%% <code>last</code> can be used to seek to the very first or
+%% last key in the database.
-type seek_dest() :: iolist() | first | last.
+
+
+%% @type error().
+%% The format for all errors reported by ErLevelDB.
-type error() :: {error, any()}.
View
157 src/erleveldb.erl
@@ -5,15 +5,17 @@
%% @copyright 2011 Paul J. Davis
%% @version 0.1.0
%% @reference <a href="http://leveldb.googlecode.com">LevelDB</a>
+%% @headerfile "erleveldb.hrl"
+%% @doc
+%% Erlang NIF driver to LevelDB.
%%
-
+%% Ohai.
-module(erleveldb).
-on_load(init/0).
-include("erleveldb.hrl").
-
-define(i2b(B), iolist_to_binary(B)).
-define(location, [{module, ?MODULE}, {line, ?LINE}]).
-define(not_loaded, erlang:nif_error(not_loaded, [?location])).
@@ -30,100 +32,227 @@
-export_type([dbopts/0, readopts/0, writeopts/0, seek_dest/0]).
+%% @doc Open an existing database.
+%% This function can be used to open a database that was
+%% created previously. <code>Name::iolist()</code> refers
+%% to the path on disk to the database.
-spec open_db(iolist()) -> {ok, db()} | error().
open_db(_Name) ->
?not_loaded.
+%% @doc Open an ErlLevelDB database.
+%% This function can open or create a database. You'll
+%% want to check out the <code>Opts::dbopts()</code> for
+%% information on all the various knobs available.
+%%
+%% @see dbopts()
-spec open_db(iolist(), dbopts()) -> {ok, db()} | error().
open_db(_Name, _Opts) ->
?not_loaded.
--spec put(db(), iolist(), iolist()) -> ok | error().
-put(_Db, _Key, _Value) ->
- ?not_loaded.
-
--spec put(db(), iolist(), iolist(), writeopts()) ->
- ok | {ok, binary()} | error().
-put(_Db, _Key, _Value, _Opts) ->
+%% @doc Create a database snapshot.
+%% Return a database snapshot. This allows for issuing
+%% read requests against a specific version of the datbase.
+%% Alternatively, the three write functions also have the
+%% ability to return snapshots that represent a snapshot
+%% just after the write is finished and before any other
+%% write occurrs.
+%%
+%% To use a snapshot you just need to pass it to either of
+%% the read methods in their readopts() options proplist.
+%%
+%% Multiple snapshots can exist for a given database at any
+%% given time. It is important to note that a database will
+%% not be closed until all snapshots are garbage collected.
+-spec snapshot(db()) -> {ok, snapshot()} | error().
+snapshot(_Db) ->
?not_loaded.
+%% @doc Retrieve a value from the database.
+%% Retrieve the value associated with the given key
+%% or return <code>{error, not_found}</code> if the
+%% key doesn't exist.
+%%
+%% @see get/3
-spec get(db(), iolist()) -> {ok, binary()} | error().
get(_Db, _Key) ->
?not_loaded.
+%% @doc Retrieve a value from the database.
+%% Retreive the value associated with the given key
+%% or return <code>{error, not_found}</code> if the
+%% key doesn't exist.
+%%
+%% @see readopts()
-spec get(db(), iolist(), readopts()) -> {ok, binary()} | error().
get(_Db, _Key, _Opts) ->
?not_loaded.
+%% @doc Store a key/value pair in the database.
+%%
+%% @see put/4
+-spec put(db(), iolist(), iolist()) -> ok | error().
+put(_Db, _Key, _Value) ->
+ ?not_loaded.
+
+
+%% @doc Store a key/value pair in the database.
+%% Write functions can also request that the database
+%% call <code>fsync(2)</code> before returning using
+%% the writeopts(). They can also request that a database
+%% snapshot() is returned.
+%%
+%% @see writeopts()
+%% @see snapshot/1
+%% @see snapshot()
+-spec put(db(), iolist(), iolist(), writeopts()) ->
+ ok | {ok, binary()} | error().
+put(_Db, _Key, _Value, _Opts) ->
+ ?not_loaded.
+
+
+%% @doc Remove a key from the database.
+%% It is not an error if the key does not exist.
+%%
+%% @see del/3
-spec del(db(), iolist()) -> ok | error().
del(_Db, _Key) ->
?not_loaded.
+%% @doc Remove a key from the database.
+%% It is not an error if the key does not exist.
+%% Write functions can also request that the database
+%% call <code>fsync(2)</code> before returning using
+%% the writeopts(). They can also request a database
+%% snapshot() is returned.
+%%
+%% @see writeopts()
+%% @see snapshot/1
+%% @see snapshot()
-spec del(db(), iolist(), writeopts()) -> ok | {ok, snapshot()} | error().
del(_Db, _Key, _Opts) ->
?not_loaded.
+%% @doc Create a database iterator.
+%% Returns a database iterator() that represents the
+%% the current state of the database.
+%%
+%% @see iter/2
-spec iter(db()) -> {ok, iterator()} | error().
iter(_Db) ->
?not_loaded.
+%% @doc Create a database iterator.
+%% Returns a database iterator(). The iterator can
+%% optionally refer to a specific version of the database
+%% if a snapshot() is specified.
+%%
+%% It is important to note that a database will not be closed
+%% until all iterators created from it are garbage collected.
+%%
+%% @see readopts()
-spec iter(db(), readopts()) -> {ok, iterator()} | error().
iter(_Db, _Opts) ->
?not_loaded.
+%% @doc Seek an iterator to specific location.
+%% This function returns they key/value pair at the
+%% location requested or the first key/value after
+%% the location request. If the specified location
+%% is beyond the end of the database then
+%% <code>{error, not_found}</code> is returned.
+%% The atom <code>first</code> or <code>last</code>
+%% can be used to seek to the first or last key
+%% respectively.
-spec seek(iterator(), seek_dest()) -> {ok, {binary(), binary()}} | error().
seek(_Iter, _Key) ->
?not_loaded.
+%% @doc Return the next key/value pair from the iterator.
+%% If no more key/value pairs are available, then
+%% <code>{error, not_found}</code> is returned.
-spec next(iterator()) -> {ok, {binary(), binary()}} | error().
next(_Iter) ->
?not_loaded.
+%% @doc Return the previous key/value pair from the iterator.
+%% If the iterator was already position before the first
+%% key in the database, then <code>{error, not_found}</code>
+%% is returned. Beware that reverse iteration may be
+%% slower than forward iteration.
-spec prev(iterator()) -> {ok, {binary(), binary()}} | error().
prev(_Iter) ->
?not_loaded.
+%% @doc Create a write_batch().
+%% A write batch is used to make multiple updates to the
+%% database in a single atomic action. It is important
+%% to remember that the order of operations is important.
+%% therefore, if you create a write batch that first put's
+%% a key/value pair and then subsequently delete's that key,
+%% the key will not exist after this write batch is executed.
+%%
+%% It is important to note that a database will not be closed
+%% until all write batches created from it have been garbage
+%% collected.
-spec batch(db()) -> {ok, write_batch()} | error().
batch(_Db) ->
?not_loaded.
+%% @doc Queue a write in the given write batch.
+%% Store the given key/value pair for a later write when this
+%% write batch is committed. Remember that the order of
+%% operations is important.
-spec wb_put(write_batch(), iolist(), iolist()) -> ok | error().
wb_put(Wb, Key, Val) when is_binary(Key) andalso is_binary(Val) ->
wb_put0(Wb, Key, Val);
wb_put(Wb, Key, Val) ->
wb_put0(Wb, ?i2b(Key), ?i2b(Val)).
+
+%% @doc Queue the removal of a key in the given write batch.
+%% Store they key for later removal when this write batch
+%% is comitted. Remember that the order of operations is
+%% important.
-spec wb_del(write_batch(), iolist()) -> ok | error().
wb_del(Wb, Key) when is_binary(Key) ->
wb_del0(Wb, Key);
wb_del(Wb, Key) ->
wb_del0(Wb, ?i2b(Key)).
+
+%% @doc Clear a write batch.
+%% Remove any wb_put or wb_del actions queued on this
+%% write batch.
-spec wb_clear(write_batch()) -> ok | error().
wb_clear(_Wb) ->
?not_loaded.
+
+%% @doc Commit a write batch to the database.
+%% Apply the queued actions as an atomic unit against the
+%% database from which it was created.
-spec wb_write(write_batch()) -> ok | error().
wb_write(_Wb) ->
?not_loaded.
+%% @doc Commit a write batch to the database.
+%% Apply the queued actions as an atomic unit against the
+%% database from which it was created.
+%%
+%% @see writeopts()
-spec wb_write(write_batch(), writeopts()) -> ok | {ok, snapshot()} | error().
wb_write(_Wb, _Opts) ->
?not_loaded.
--spec snapshot(db()) -> {ok, snapshot()} | error().
-snapshot(_Db) ->
- ?not_loaded.
-
-
% Internal API
%% @private

0 comments on commit aca7399

Please sign in to comment.