Commits

Anonymous committed 536f6dc

edoc-enabled. do 'make e'.

Comments (0)

Files changed (2)

 %% -*- coding: utf-8 -*-
+%% @author kuenishi
+%% @copyright -
+%% @doc tcadb module. use this module as a TokyoCabinet wrapper. Yatce is a thin wrapper 
+%% of TokyoCabinet, so `tcadb''s  APIs are almost same as those of TokyoCabinet.
+%% @reference <a href="http://bitbucket.org/kuenishi/yatce">source repository site</a>
+%% @reference <a href="http://erlang.org/doc/man/erl_nif.html">NIF</a>
+%% @reference <a href="http://1978th.net/tokyocabinet/spex-ja.html#tcadbapi">Basic spex in Japanese</a>
+%% @reference <a href="http://1978th.net/tokyocabinet/spex-en.html#tcadbapi">Basic spex in English</a>
 
 -module(tcadb).
 -author('kuenishi+tc@gmail.com').
 
+% @type tablename() = atom()
+% @type proplist() = [ property() ]
+% where property() = { atom(), term() }
+% @type key() = term()
+% @type value() = term()
 -include("tokyocabinet.hrl").
-%% OO type interface, going to be compliant with tokyocabinet.idl
-%% see http://d.hatena.ne.jp/cooldaemon/20080502/1209716211
 
 -export([          
 	 init/0,
-   %%   interface ADB { //from tokyocabinet.idl
-	 open/2,      %%     boolean open(in string name);
-	 close/1,     %%     boolean close();
-	 put/3,       %%     boolean put(in string key, in string value);
-	 putkeep/3,   %%     boolean putkeep(in string key, in string value);
-%	 putcat/2,    %%     boolean putcat(in string key, in string value);
-	 out/2,       %%     boolean out(in string key);
-	 get/2,       %%     string get(in string key);
-		      %%     long vsiz(in string key);
-	 iterinit/1,  %%     boolean iterinit();
-	 iternext/1,  %%     string iternext();
-		      %%     List fwmkeys(in string prefix, in long max);
-	              %%     long addint(in string key, in long num);
-	              %%     double adddouble(in string key, in double num);
-	 sync/1,      %%     boolean sync();
-%	 optimize/1,  %%     boolean optimize(in string params);
-	 vanish/1,    %%     boolean vanish();
-	 copy/2,      %%     boolean copy(in string path);
-%	 tx/1,	      %%     boolean tranbegin();
-		      %%     boolean trancommit();
-		      %%     boolean tranabort();
-	 path/1,      %%     string path();
-	 rnum/1,      %%     long long rnum(); #of records
-	 size/1       %%     long long size();
+	 open/2,
+	 close/1,
+	 put/3,
+	 putkeep/3,
+	 %putcat/2, putcat will never be supported on yatce.
+	 out/2,
+	 get/2,
+	 iterinit/1,
+	 iternext/1,
+	 sync/1,
+	 %optimize/1,  %%     boolean optimize(in string params);
+	 vanish/1,
+	 copy/2,
+	 %tx/1,	      %%     boolean tranbegin(); boolean trancommit();  boolean tranabort();
+	 path/1,
+	 rnum/1,
+	 size/1
 		      %%     List misc(in string name, in List args);
 	]).
 
-
+%% @doc load the nif library for tcadb. make sure that libyatce.so is in where erts can find.
+%% @since 0.20.0
+%% @spec init() -> ok | error
 -spec init() -> 'ok'.
 init()->
     case code:priv_dir(?MODULE) of
 		{ok,NPath} when is_list(NPath)->
 		    erlang:load_nif(filename:join([NPath, ?DYLIB_NAME]), 0);
 		_ -> 
-		    errorhoge
+		    error
 	    end
     end.
 
+%% @private
 find_path_([])->
     {error, not_found};
 find_path_([Head|Tail])->
     	    find_path_(Tail)
     end.
 
--spec open( atom(), list() ) -> ok | {error, tcadbopen_failure} | not_loaded.
+%% @doc Create a new TCADB instance. you can use this TCADB concurrently.
+%% `TableName' specifies the name of the database. <br/>
+%% If it is "*", the database will be an on-memory hash database. If it is "+", the database will be an on-memory tree database. If its suffix is ".tch", the database will be a hash database. If its suffix is ".tcb", the database will be a B+ tree database. If its suffix is ".tcf", the database will be a fixed-length database. If its suffix is ".tct", the database will be a table database. Otherwise, this function fails. <em>In yatce, tct and tcf isn't supported.</em><br/>
+%% Tuning parameters can trail the name, separated by "#". 
+%% Each parameter is composed of the name and the value, separated by "=". 
+%% - On-memory hash database supports "bnum", "capnum", and "capsiz". 
+%% - On-memory tree database supports "capnum" and "capsiz". 
+%% - Hash database supports "mode", "bnum", "apow", "fpow", "opts", "rcnum", "xmsiz", and "dfunit". 
+%% - B+ tree database supports "mode", "lmemb", "nmemb", "bnum", "apow", "fpow", "opts", "lcnum", "ncnum", "xmsiz", and "dfunit".
+%% - Fixed-length database supports "mode", "width", and "limsiz". 
+%% - Table database supports "mode", "bnum", "apow", "fpow", "opts", "rcnum", "lcnum", "ncnum", "xmsiz", "dfunit", and "idx".
+%% == Tuning parameters ==
+%% <ul><li> The tuning parameter "capnum" specifies the capacity number of records.  </li>
+%% <li> "capsiz" specifies the capacity size of using memory. Records spilled the capacity are removed by the storing order. </li>
+%% <li> "mode" can contain "w" of writer, "r" of reader, "c" of creating, "t" of truncating, "e" of no locking, and "f" of non-blocking lock. The default mode is relevant to "wc". </li>
+%% <li> "opts" can contains "l" of large option, "d" of Deflate option, "b" of BZIP2 option, and "t" of TCBS option. </li>
+%% <li> "idx" specifies the column name of an index and its type separated by ":".  </li>
+%% </ul>
+%% For example, "casket.tch#bnum=1000000#opts=ld" means that the name of the database file is "casket.tch", and the bucket number is 1000000, and the options are large and Deflate.
+%% @since 0.1.0
+%% @spec open( tablename(), proplist() ) -> ok | not_loaded | {error, reason()}
+-spec open( tablename(), list() ) -> ok | {error, tcadbopen_failure} | not_loaded.
 open('*', Options) ->
     open_("*", generate_open_argv("*", Options));
 open('+', Options) ->
 
 make_table_identifier(TableName) when is_atom(TableName)->  atom_to_list(TableName).
 
-
-%% Create a new TCADB instance. you can use this TCADB concurrently.
-%% Take care when closing the instance.
-%% http://tokyocabinet.sourceforge.net/spex-ja.html#tcadbapi
-%% `name' specifies the name of the database. 
-%% If it is "*", the database will be an on-memory hash database. If it is "+", the database will be an on-memory tree database. If its suffix is ".tch", the database will be a hash database. If its suffix is ".tcb", the database will be a B+ tree database. If its suffix is ".tcf", the database will be a fixed-length database. If its suffix is ".tct", the database will be a table database. Otherwise, this function fails. 
-%% Tuning parameters can trail the name, separated by "#". 
-%% Each parameter is composed of the name and the value, separated by "=". 
-%% - On-memory hash database supports "bnum", "capnum", and "capsiz". 
-%% - On-memory tree database supports "capnum" and "capsiz". 
-%% - Hash database supports "mode", "bnum", "apow", "fpow", "opts", "rcnum", "xmsiz", and "dfunit". 
-%% - B+ tree database supports "mode", "lmemb", "nmemb", "bnum", "apow", "fpow", "opts", "lcnum", "ncnum", "xmsiz", and "dfunit".
-%% - Fixed-length database supports "mode", "width", and "limsiz". 
-%% - Table database supports "mode", "bnum", "apow", "fpow", "opts", "rcnum", "lcnum", "ncnum", "xmsiz", "dfunit", and "idx".
-%% Tuning parameters
-%% + The tuning parameter "capnum" specifies the capacity number of records. 
-%% "capsiz" specifies the capacity size of using memory. Records spilled the capacity are removed by the storing order. 
-%% "mode" can contain "w" of writer, "r" of reader, "c" of creating, "t" of truncating, "e" of no locking, and "f" of non-blocking lock. The default mode is relevant to "wc". 
-%% "opts" can contains "l" of large option, "d" of Deflate option, "b" of BZIP2 option, and "t" of TCBS option. 
-%% "idx" specifies the column name of an index and its type separated by ":". 
-%% For example, "casket.tch#bnum=1000000#opts=ld" means that the name of the database file is "casket.tch", and the bucket number is 1000000, and the options are large and Deflate.
 -type option_key() :: bnum | capnum | capsiz | mode | bnum | apow | fpow | opts | rcnum | xmsiz | dfunit .
 -type option_value() :: pos_integer() | list() .
 -type open_option() :: { option_key(), option_value() }.
     StrKey = atom_to_list(Key),
     generate_open_argv( TableName++"#"++StrKey++"="++Value, Options).
 
-
--spec close( atom() ) -> {ok, closed} | {error, tcadbclose_failure}.
+%% @doc closes the database.
+%% @spec close( tablename() )-> ok | not_loaded
+%% @since 0.1.0
+-spec close( tablename() ) -> ok | not_loaded.
 close(TableName) when is_atom(TableName)-> 
     close_( make_table_identifier(TableName) ).
 
 close_(_)-> not_loaded.     
 
--spec put( atom(), key(), value()) -> {ok, inserted} | {error,  'tcadbput(keep)_failure'}.
+%% @doc insert data into the table.
+%% @spec put( tablename(), key(), value() )-> ok | failed | not_loaded
+%% @since 0.10.0
+-spec put( tablename(), key(), value()) -> ok | failed | not_loaded.
 put(TableName, Key, Value) when is_atom(TableName)->
     put_(make_table_identifier(TableName), term_to_binary(Key), term_to_binary(Value) ).
 
 put_(_,_,_) -> not_loaded.
 
--spec putkeep(atom(), key(), value()) -> {ok, inserted} | {error,  'tcadbput(keep)_failure'}.
+%% @doc insert data into the table only if the record doesn't exist.
+%% @spec putkeep( tablename(), key(), value() )-> ok | failed | not_loaded
+%% @since 0.10.0
+-spec putkeep(tablename(), key(), value()) -> ok | failed | not_loaded.
 putkeep(TableName, Key, Value) when is_atom(TableName)->
     putkeep_(make_table_identifier(TableName), term_to_binary(Key), term_to_binary(Value) ).
 
 putkeep_(_,_,_)->not_loaded.
 
--spec out(atom(), key()) -> {ok, inserted} | {error,  'tcadbout_failure'}.
+%% @doc remove record from table.
+%% @spec out( tablename(), key() )-> ok | failed | not_loaded
+%% @since 0.10.0
+-spec out(tablename(), key()) -> ok | failed | not_loaded.
 out(TableName, Key) when is_atom(TableName)->
     out_(make_table_identifier(TableName), term_to_binary(Key)).
 
 out_(_,_)-> not_loaded.
 
--spec get(atom(), key() )-> {ok, value()} | {error, record_doesnt_exist}.
+%% @doc get record value from the table.
+%% @spec get( tablename(), key() )-> {ok, value()} | failed | not_loaded
+%% @since 0.10.0
+-spec get(tablename(), key() )-> {ok, value()} | failed | not_loaded.
 get(TableName, Key) when is_atom(TableName)->
     case get_(make_table_identifier(TableName), term_to_binary(Key)) of
 	{ok,Bin}->   {ok,binary_to_term(Bin)};
 
 get_(_,_)-> not_loaded.
 
--spec iterinit(atom()) -> ok | {error, failed}.
+%% @doc initialize the iterator on the table.
+%% @spec iterinit( tablename() )-> ok | failed | not_loaded
+%% @since 0.10.0
+-spec iterinit(tablename()) -> ok | failed | not_loaded.
 iterinit(TableName) when is_atom(TableName)->
     iterinit_(make_table_identifier(TableName)).
 iterinit_(_)-> not_loaded.
 
--spec iternext(atom()) -> {key(), value()} | eod | error.
+%% @doc get next key from the iterator of the table.
+%% @spec iternext( tablename() )-> {ok,key()} | eod | not_loaded
+%% @since 0.10.0
+-spec iternext( tablename()) -> {ok,key()} | eod | not_loaded.
 iternext(TableName) when is_atom(TableName)->
     case iternext_(make_table_identifier(TableName)) of
 	{ok,Bin}->   {ok,binary_to_term(Bin)};
 	    
 iternext_(_)-> not_loaded.
 
--spec sync(atom()) -> ok | {error, not_synced}.
+%% @doc do fsync to the database.
+%% @spec sync( tablename() )-> ok | fail | not_loaded
+%% @since 0.10.0
+-spec sync(tablename()) -> ok | error | not_loaded.
 sync(TableName) when is_atom(TableName)-> sync_(make_table_identifier(TableName)).
 sync_(_)-> not_loaded.
 
 optimize(_)->
     {error, not_yet_supported}.
 
--spec vanish(atom()) -> ok | {error, not_vanished}.
+%% @doc remove all records from table database.
+%% @spec vanish( tablename() )-> ok | fail | not_loaded
+%% @since 0.10.0
+-spec vanish(tablename()) -> ok | fail | not_loaded.
 vanish(TableName) when is_atom(TableName)-> vanish_(make_table_identifier(TableName)).
 vanish_(_)-> not_loaded.
 
+%% @doc copy the database file with consistent state.
+%% @spec copy( tablename(), filename() )-> ok | fail | not_loaded
+%% @since 0.20.0
+-spec copy(tablename(), filename:filename()) -> ok | fail | not_loaded.
 copy(TableName, Filename) when is_atom(TableName) and is_list(Filename) -> 
     copy_(make_table_identifier(TableName), Filename).
 copy_(_,_)-> not_loaded.
 
--spec path(atom()) -> tablename().
+%% @doc get full path of the file which the table database belongs to.
+%% @spec path( tablename() )-> filename() | fail | not_loaded
+%% @since 0.10.0
+-spec path(tablename()) -> filename:filename() | not_loaded.
 path(TableName) when is_atom(TableName)-> path_(make_table_identifier(TableName)).
 path_(_)-> not_loaded.
      
--spec rnum(atom()) -> non_neg_integer().
+%% @doc get #of records in the table.
+%% @spec rnum( tablename() )-> non_neg_integer() | fail | not_loaded
+%% @since 0.10.0
+-spec rnum(tablename()) -> non_neg_integer() | not_loaded.
 rnum(TableName) when is_atom(TableName)-> rnum_(make_table_identifier(TableName)).
 rnum_(_)-> not_loaded.
 
--spec size(atom()) -> non_neg_integer().
+%% @doc get size of the table database file. 
+%% @spec size( tablename() )-> non_neg_integer() | fail | not_loaded
+%% @since 0.10.0
+-spec size(tablename()) -> non_neg_integer() | not_loaded.
 size(TableName) when is_atom(TableName)-> size_(make_table_identifier(TableName)).
 size_(_)-> not_loaded.

src/tokyocabinet.hrl

 %% -*- coding: utf-8 -*-
 -define(DYLIB_NAME, "libyatce").
--define(IS_LOADED, libyatce_process).
-
--define(IS_ATOM,   101).
--define(IS_LIST,   102). %% a simple string
--define(IS_RAW,    103).
-
-%% must match c_src/tokyocabinet.h
--define(YATCE_OPEN,   16#80101).
--define(YATCE_CLOSE,  16#80201).
--define(YATCE_PUT,    16#80307).
--define(YATCE_PKEEP,16#80407).
-%%-define(YATCE_PUTCAT, 16#80507).
--define(YATCE_OUT,    16#80603).
--define(YATCE_GET,    16#80703).
--define(YATCE_ITERINIT, 16#80901).
--define(YATCE_ITERNEXT, 16#81001).
--define(YATCE_ADDINT, 16#81207).
--define(YATCE_ADDDOUBLE,16#81307).
--define(YATCE_SYNC,   16#81401).
--define(YATCE_OPTIMIZE, 16#81501).
--define(YATCE_VANISH, 16#81601).
--define(YATCE_COPY,   16#81701).
-%-define(YATCE_TX,     16#81807).
--define(YATCE_PATH,   16#81901).
-
--define(YATCE_RNUM,   16#82201).
--define(YATCE_SIZE,   16#82301).
-
--define(YATCE_TEST,   16#90000).
-
 
 %% types
+
 -type option() :: {libdir, list()}.
 -type tablename() :: atom().
--type tcadb() :: {tcadb, tablename(), [option()], port()}.
-
--type erl_ddll_error_desc() :: linked_in_driver | inconsistent | permanent |
-                     not_loaded_by_this_process | not_loaded |  pending_reload
-                     | pending_process.
-
 -type key() :: string() | integer().
 -type value() :: string() | number() | binary().