Added skeleton documentation.

This commit is contained in:
Phillip Toland 2009-02-18 17:11:12 -06:00
parent 8b13a5aefe
commit da4386967d

View file

@ -1,8 +1,9 @@
%% -------------------------------------------------------------------
%% @doc
%% Erlang interface to BerkeleyDB.
%%
%% bdberl: Interface to BerkeleyDB
%% Copyright (c) 2008 The Hive. All rights reserved.
%%
%% @copyright 2008-9 The Hive. All rights reserved.
%% @end
%% -------------------------------------------------------------------
-module(bdberl).
@ -47,6 +48,20 @@
-type db_update_fun_args() :: undefined | [term()].
%%--------------------------------------------------------------------
%% @doc
%% Open a database file, creating it if it does not exist.
%%
%% @spec open(Name, Type) -> {ok, Db} | {error, Error}
%% where
%% Name = string()
%% Type = btree | hash
%% Db = integer()
%%
%% @equiv open(Name, Type, [create])
%% @see open/3
%% @end
%%--------------------------------------------------------------------
-spec open(Name :: db_name(), Type :: db_type()) ->
{ok, db()} | {error, integer()}.
@ -54,6 +69,19 @@ open(Name, Type) ->
open(Name, Type, [create]).
%%--------------------------------------------------------------------
%% @doc
%% Open a database file.
%%
%% @spec open(Name, Type, Opts) -> {ok, Db} | {error, Error}
%% where
%% Name = string()
%% Type = btree | hash
%% Opts = [atom()]
%% Db = integer()
%%
%% @end
%%--------------------------------------------------------------------
-spec open(Name :: db_name(), Type :: db_type(), Opts :: db_flags()) ->
{ok, db()} | {error, integer()}.
@ -73,12 +101,35 @@ open(Name, Type, Opts) ->
end.
%%--------------------------------------------------------------------
%% @doc
%% Close a database file.
%%
%% @spec close(Db) -> ok | {error, Error}
%% where
%% Db = integer()
%%
%% @equiv close(Db, [])
%% @see close/2
%% @end
%%--------------------------------------------------------------------
-spec close(Db :: db()) -> ok | db_error().
close(Db) ->
close(Db, []).
%%--------------------------------------------------------------------
%% @doc
%% Close a database file.
%%
%% @spec close(Db, Opts) -> ok | {error, Error}
%% where
%% Db = integer()
%% Opts = [atom()]
%%
%% @end
%%--------------------------------------------------------------------
-spec close(Db :: db(), Opts :: db_flags()) -> ok | db_error().
close(Db, Opts) ->
@ -93,12 +144,32 @@ close(Db, Opts) ->
end.
%%--------------------------------------------------------------------
%% @doc
%% Begin a transaction.
%%
%% @spec txn_begin() -> ok | {error, Error}
%%
%% @equiv txn_begin([])
%% @see txn_begin/1
%% @end
%%--------------------------------------------------------------------
-spec txn_begin() -> ok | db_error().
txn_begin() ->
txn_begin([]).
%%--------------------------------------------------------------------
%% @doc
%% Begin a transaction.
%%
%% @spec txn_begin(Opts) -> ok | {error, Error}
%% where
%% Opts = [atom()]
%%
%% @end
%%--------------------------------------------------------------------
-spec txn_begin(Opts :: db_flags()) -> ok | db_error().
txn_begin(Opts) ->
@ -111,12 +182,32 @@ txn_begin(Opts) ->
end.
%%--------------------------------------------------------------------
%% @doc
%% Commit a transaction.
%%
%% @spec txn_commit() -> ok | {error, Error}
%%
%% @equiv txn_commit([])
%% @see txn_commit/1
%% @end
%%--------------------------------------------------------------------
-spec txn_commit() -> ok | db_error().
txn_commit() ->
txn_commit([]).
%%--------------------------------------------------------------------
%% @doc
%% Commit a transaction.
%%
%% @spec txn_commit(Opts) -> ok | {error, Error}
%% where
%% Opts = [atom()]
%%
%% @end
%%--------------------------------------------------------------------
-spec txn_commit(Opts :: db_flags()) -> ok | db_error().
txn_commit(Opts) ->
@ -134,6 +225,14 @@ txn_commit(Opts) ->
end.
%%--------------------------------------------------------------------
%% @doc
%% Abort a transaction.
%%
%% @spec txn_abort() -> ok | {error, Error}
%%
%% @end
%%--------------------------------------------------------------------
-spec txn_abort() -> ok | db_error().
txn_abort() ->
@ -153,12 +252,35 @@ txn_abort() ->
end.
%%--------------------------------------------------------------------
%% @doc
%% Execute a fun inside of a transaction.
%%
%% @spec transaction(Fun) -> {ok, Value} | {error, Error}
%% where
%% Fun = function()
%%
%% @equiv transaction(Fun, infinity)
%% @see transaction/2
%% @end
%%--------------------------------------------------------------------
-spec transaction(Fun :: txn_fun()) -> {ok, db_value()} | db_error().
transaction(Fun) ->
transaction(Fun, infinity).
%%--------------------------------------------------------------------
%% @doc
%% Execute a fun inside of a transaction.
%%
%% @spec transaction(Fun, Retries) -> {ok, Value} | {error, Error}
%% where
%% Fun = function()
%% Retries = infinity | integer()
%%
%% @end
%%--------------------------------------------------------------------
-spec transaction(Fun :: txn_fun(), Retries :: txn_retries()) ->
{ok, db_value()} | {error, db_error_reason() | {transaction_failed, term()}}.
@ -198,6 +320,20 @@ transaction(Fun, Retries) ->
end.
%%--------------------------------------------------------------------
%% @doc
%% Store a value in a database file.
%%
%% @spec put(Db, Key, Value) -> ok | {error, Error}
%% where
%% Db = integer()
%% Key = any()
%% Value = any()
%%
%% @equiv put(Db, Key, Value, [])
%% @see put/4
%% @end
%%--------------------------------------------------------------------
-spec put(Db :: db(), Key :: db_key(), Value :: db_value()) ->
ok | db_error().
@ -205,6 +341,19 @@ put(Db, Key, Value) ->
put(Db, Key, Value, []).
%%--------------------------------------------------------------------
%% @doc
%% Store a value in a database file.
%%
%% @spec put(Db, Key, Value, Opts) -> ok | {error, Error}
%% where
%% Db = integer()
%% Key = any()
%% Value = any()
%% Opts = [atom()]
%%
%% @end
%%--------------------------------------------------------------------
-spec put(Db :: db(), Key :: db_key(), Value :: db_value(), Opts :: db_flags()) ->
ok | db_error().
@ -212,12 +361,43 @@ put(Db, Key, Value, Opts) ->
do_put(?CMD_PUT, Db, Key, Value, Opts).
%%--------------------------------------------------------------------
%% @doc
%% Store a value in a database file.
%%
%% @spec put_r(Db, Key, Value) -> ok
%% where
%% Db = integer()
%% Key = any()
%% Value = any()
%%
%% @throws {error, Error}
%%
%% @equiv put_r(Db, Key, Value, [])
%% @see put_r/4
%% @end
%%--------------------------------------------------------------------
-spec put_r(Db :: db(), Key :: db_key(), Value :: db_value()) -> ok.
put_r(Db, Key, Value) ->
put_r(Db, Key, Value, []).
%%--------------------------------------------------------------------
%% @doc
%% Store a value in a database file.
%%
%% @spec put_r(Db, Key, Value, Opts) -> ok
%% where
%% Db = integer()
%% Key = any()
%% Value = any()
%% Opts = [atom()]
%%
%% @throws {error, Error}
%%
%% @end
%%--------------------------------------------------------------------
-spec put_r(Db :: db(), Key :: db_key(), Value :: db_value(), Opts :: db_flags()) -> ok.
put_r(Db, Key, Value, Opts) ->
@ -227,6 +407,20 @@ put_r(Db, Key, Value, Opts) ->
end.
%%--------------------------------------------------------------------
%% @doc
%% Store a value in a database file.
%%
%% @spec put_commit(Db, Key, Value) -> ok | {error, Error}
%% where
%% Db = integer()
%% Key = any()
%% Value = any()
%%
%% @equiv put_commit(Db, Key, Value, [])
%% @see put_commit/4
%% @end
%%--------------------------------------------------------------------
-spec put_commit(Db :: db(), Key :: db_key(), Value :: db_value()) ->
ok | db_error().
@ -234,6 +428,19 @@ put_commit(Db, Key, Value) ->
put_commit(Db, Key, Value, []).
%%--------------------------------------------------------------------
%% @doc
%% Store a value in a database file.
%%
%% @spec put_commit(Db, Key, Value, Opts) -> ok | {error, Error}
%% where
%% Db = integer()
%% Key = any()
%% Value = any()
%% Opts = [atom()]
%%
%% @end
%%--------------------------------------------------------------------
-spec put_commit(Db :: db(), Key :: db_key(), Value :: db_value(), Opts :: db_flags()) ->
ok | db_error().
@ -241,12 +448,43 @@ put_commit(Db, Key, Value, Opts) ->
do_put(?CMD_PUT_COMMIT, Db, Key, Value, Opts).
%%--------------------------------------------------------------------
%% @doc
%% Store a value in a database file.
%%
%% @spec put_commit_r(Db, Key, Value) -> ok
%% where
%% Db = integer()
%% Key = any()
%% Value = any()
%%
%% @throws {error, Error}
%%
%% @equiv put_commit_r(Db, Key, Value, [])
%% @see put_commit_r/4
%% @end
%%--------------------------------------------------------------------
-spec put_commit_r(Db :: db(), Key :: db_key(), Value :: db_value()) -> ok.
put_commit_r(Db, Key, Value) ->
put_commit_r(Db, Key, Value, []).
%%--------------------------------------------------------------------
%% @doc
%% Store a value in a database file.
%%
%% @spec put_commit_r(Db, Key, Value, Opts) -> ok
%% where
%% Db = integer()
%% Key = any()
%% Value = any()
%% Opts = [atom()]
%%
%% @throws {error, Error}
%%
%% @end
%%--------------------------------------------------------------------
-spec put_commit_r(Db :: db(), Key :: db_key(), Value :: db_value(), Opts :: db_flags()) -> ok.
put_commit_r(Db, Key, Value, Opts) ->
@ -256,6 +494,19 @@ put_commit_r(Db, Key, Value, Opts) ->
end.
%%--------------------------------------------------------------------
%% @doc
%% Retrieve a value based on key.
%%
%% @spec get(Db, Key) -> not_found | {ok, Value} | {error, Error}
%% where
%% Db = integer()
%% Key = term()
%%
%% @equiv get(Db, Key, [])
%% @see get/3
%% @end
%%--------------------------------------------------------------------
-spec get(Db :: db(), Key :: db_key()) ->
not_found | {ok, db_ret_value()} | db_error().
@ -263,6 +514,18 @@ get(Db, Key) ->
get(Db, Key, []).
%%--------------------------------------------------------------------
%% @doc
%% Retrieve a value based on key.
%%
%% @spec get(Db, Key, Opts) -> not_found | {ok, Value} | {error, Error}
%% where
%% Db = integer()
%% Key = term()
%% Opts = [atom()]
%%
%% @end
%%--------------------------------------------------------------------
-spec get(Db :: db(), Key :: db_key(), Opts :: db_flags()) ->
not_found | {ok, db_ret_value()} | db_error().
@ -283,6 +546,21 @@ get(Db, Key, Opts) ->
end.
%%--------------------------------------------------------------------
%% @doc
%% Retrieve a value based on key.
%%
%% @spec get_r(Db, Key) -> not_found | {ok, Value}
%% where
%% Db = integer()
%% Key = term()
%%
%% @throws {error, Error}
%%
%% @equiv get_r(Db, Key, [])
%% @see get_r/3
%% @end
%%--------------------------------------------------------------------
-spec get_r(Db :: db(), Key :: db_key()) ->
not_found | {ok, db_ret_value()}.
@ -290,6 +568,20 @@ get_r(Db, Key) ->
get_r(Db, Key, []).
%%--------------------------------------------------------------------
%% @doc
%% Retrieve a value based on key.
%%
%% @spec get_r(Db, Key, Opts) -> not_found | {ok, Value}
%% where
%% Db = integer()
%% Key = term()
%% Opts = [atom()]
%%
%% @throws {error, Error}
%%
%% @end
%%--------------------------------------------------------------------
-spec get_r(Db :: db(), Key :: db_key(), Opts :: db_flags()) ->
not_found | {ok, db_ret_value()}.
@ -301,6 +593,20 @@ get_r(Db, Key, Opts) ->
end.
%%--------------------------------------------------------------------
%% @doc
%% Updates the value of a key by executing a fun.
%%
%% @spec update(Db, Key, Fun) -> {ok, Value} | {error, Error}
%% where
%% Db = integer()
%% Key = term()
%% Fun = function()
%%
%% @equiv update(Db, Key, Fun, undefined)
%% @see update/4
%% @end
%%--------------------------------------------------------------------
-spec update(Db :: db(), Key :: db_key(), Fun :: db_update_fun()) ->
{ok, db_value()} | db_error().
@ -308,6 +614,19 @@ update(Db, Key, Fun) ->
update(Db, Key, Fun, undefined).
%%--------------------------------------------------------------------
%% @doc
%% Updates the value of a key by executing a fun.
%%
%% @spec update(Db, Key, Fun, Args) -> {ok, Value} | {error, Error}
%% where
%% Db = integer()
%% Key = term()
%% Fun = function()
%% Args = any()
%%
%% @end
%%--------------------------------------------------------------------
-spec update(Db :: db(), Key :: db_key(), Fun :: db_update_fun(), Args :: db_update_fun_args()) ->
{ok, db_value()} | db_error().
@ -327,12 +646,30 @@ update(Db, Key, Fun, Args) ->
transaction(F).
%%--------------------------------------------------------------------
%% @doc
%% Truncates all of the open databases.
%%
%% @spec truncate() -> ok | {error, Error}
%%
%% @end
%%--------------------------------------------------------------------
-spec truncate() -> ok | db_error().
truncate() ->
truncate(-1).
%%--------------------------------------------------------------------
%% @doc
%% Truncates a database.
%%
%% @spec truncate(Db) -> ok | {error, Error}
%% where
%% Db = integer()
%%
%% @end
%%--------------------------------------------------------------------
-spec truncate(Db :: -1 | db()) -> ok | db_error().
truncate(Db) ->
@ -350,6 +687,16 @@ truncate(Db) ->
end.
%%--------------------------------------------------------------------
%% @doc
%% Opens a cursor on a database.
%%
%% @spec cursor_open(Db) -> {ok, Db} | {error, Error}
%% where
%% Db = integer()
%%
%% @end
%%--------------------------------------------------------------------
-spec cursor_open(Db :: db()) -> ok | db_error().
cursor_open(Db) ->
@ -363,24 +710,56 @@ cursor_open(Db) ->
end.
%%--------------------------------------------------------------------
%% @doc
%% Returns the next cursor value.
%%
%% @spec cursor_next() -> not_found | {ok, Key, Value} | {error, Error}
%%
%% @end
%%--------------------------------------------------------------------
-spec cursor_next() -> {ok, db_key(), db_value()} | not_found | db_error().
cursor_next() ->
do_cursor_move(?CMD_CURSOR_NEXT).
%%--------------------------------------------------------------------
%% @doc
%% Returns the previous cursor value.
%%
%% @spec cursor_prev() -> not_found | {ok, Key, Value} | {error, Error}
%%
%% @end
%%--------------------------------------------------------------------
-spec cursor_prev() -> {ok, db_key(), db_value()} | not_found | db_error().
cursor_prev() ->
do_cursor_move(?CMD_CURSOR_PREV).
%%--------------------------------------------------------------------
%% @doc
%% Returns the current cursor value.
%%
%% @spec cursor_current() -> not_found | {ok, Key, Value} | {error, Error}
%%
%% @end
%%--------------------------------------------------------------------
-spec cursor_current() -> {ok, db_key(), db_value()} | not_found | db_error().
cursor_current() ->
do_cursor_move(?CMD_CURSOR_CURR).
%%--------------------------------------------------------------------
%% @doc
%% Closes the cursor.
%%
%% @spec cursor_close() -> ok | {error, Error}
%%
%% @end
%%--------------------------------------------------------------------
-spec cursor_close() -> ok | db_error().
cursor_close() ->
@ -393,6 +772,16 @@ cursor_close() ->
end.
%%--------------------------------------------------------------------
%% @doc
%% Delete a database file.
%%
%% @spec delete_database(Filename) -> ok | {error, Error}
%% where
%% Filename = string()
%%
%% @end
%%--------------------------------------------------------------------
-spec delete_database(Filename :: db_name()) ->
ok | db_error().
@ -407,6 +796,16 @@ delete_database(Filename) ->
end.
%%--------------------------------------------------------------------
%% @doc
%% Returns the list of directories that bdberl searches to find databases.
%%
%% @spec get_data_dirs() -> [DirName] | {error, Error}
%% where
%% DirName = string()
%%
%% @end
%%--------------------------------------------------------------------
-spec get_data_dirs() -> [db_name(),...] | db_error().
get_data_dirs() ->
@ -433,6 +832,18 @@ get_data_dirs() ->
end.
%%--------------------------------------------------------------------
%% @doc
%% Returns the size of the in-memory cache.
%%
%% @spec get_cache_size() -> {ok, Gbytes, Mbytes, NumCaches} | {error, Error}
%% where
%% Gbytes = integer()
%% Mbytes = integer()
%% NumCaches = integer()
%%
%% @end
%%--------------------------------------------------------------------
-spec get_cache_size() ->
{ok, non_neg_integer(), non_neg_integer(), non_neg_integer()} | db_error().
@ -448,6 +859,16 @@ get_cache_size() ->
end.
%%--------------------------------------------------------------------
%% @doc
%% Returns the transaction timeout value.
%%
%% @spec get_txn_timeout() -> {ok, Timeout} | {error, Error}
%% where
%% Timeout = integer()
%%
%% @end
%%--------------------------------------------------------------------
-spec get_txn_timeout() -> {ok, non_neg_integer()} | db_error().
get_txn_timeout() ->