Merge branch 'release/0.2.12'

.gitignore

@@ -11,3 +11,4 @@ c_src/libcutil
 leo_dcerl.dot
 leo_dcerl.png
 .rebar/
+doc/

include/leo_dcerl.hrl

@@ -25,16 +25,17 @@
 
 %% dcerl's inner state
 -record(dcerl_state, {
-    journaldir_path   = "" :: string(),
-    journalfile_iodev      :: file:io_device(),
-    datadir_path      = "" :: string(),
-    max_cache_size    = 0  :: pos_integer(),
-    chunk_size        = 64 :: pos_integer(),
-    redundant_op_cnt  = 0  :: non_neg_integer(),
-    ongoing_keys           :: set(),
-    cache_metas            :: dict(),
-    cache_stats            :: #cache_stats{},
-    cache_entries          :: term() % NIF resource
+    journaldir_path    = ""        :: string(),
+    journalfile_iodev  = undefined :: file:io_device()|undefined,
+    tmp_datafile_iodev = undefined :: file:io_device()|undefined,
+    datadir_path       = ""        :: string(),
+    max_cache_size     = 0         :: pos_integer(),
+    chunk_size         = 64        :: pos_integer(),
+    redundant_op_cnt   = 0         :: non_neg_integer(),
+    ongoing_keys                   :: set(),
+    cache_metas                    :: dict(),
+    cache_stats                    :: #cache_stats{},
+    cache_entries                  :: term() % NIF resource
 }).
 
 -define(JOURNAL_FNAME, "journal").

make_rst_doc.sh

@@ -0,0 +1,20 @@
+#!/bin/sh
+
+make doc
+rm -rf doc/rst && mkdir doc/rst
+
+for Mod in leo_dcerl \
+           leo_dcerl_server
+do
+    read_file="doc/$Mod.html"
+    write_file="doc/rst/$Mod.rst"
+
+    pandoc --read=html --write=rst "$read_file" -o "$write_file"
+
+    sed -ie "1,6d" "$write_file"
+    sed -ie "1s/\Module //" "$write_file"
+    LINE_1=`cat $write_file | wc -l`
+    LINE_2=`expr $LINE_1 - 10`
+    sed -ie "$LINE_2,\$d" "$write_file"
+done
+rm -rf doc/rst/*.rste

rebar.config

@@ -20,7 +20,7 @@
 %% under the License.
 %%
 %%======================================================================
-{require_otp_vsn, "R15B03|R16B*|17"}.
+{require_otp_vsn, "R16B*|17"}.
 
 {erl_opts, [{d, 'NOTEST'},
             warn_obsolete_guard,

src/leo_dcerl.app.src

@@ -23,7 +23,7 @@
 {application, leo_dcerl,
  [{description, "Erlang disk based SSD-Aware caching library"},
   {mod, {leo_dcerl, []}},
-  {vsn, "0.2.11"},
+  {vsn, "0.2.12"},
   {registered, []},
   {applications, [kernel, stdlib]}
  ]}.

src/leo_dcerl.erl

@@ -20,7 +20,8 @@
 %%
 %% ---------------------------------------------------------------------
 %% Leo Disk Cache
-%% @doc
+%% @doc The disc cache API
+%% @reference https://github.com/leo-project/leo_dcerl/blob/master/src/leo_dcerl.erl
 %% @end
 %%======================================================================
 -module(leo_dcerl).
@@ -174,6 +175,7 @@ put_begin(#dcerl_state{journalfile_iodev = undefined} = _State, _Key) ->
     {error, badarg};
 put_begin(#dcerl_state{datadir_path      = DataDir,
                        ongoing_keys      = OnKeys,
+                       tmp_datafile_iodev = undefined,
                        journalfile_iodev = IoDev} = State, BinKey) ->
     try
         StrKey = filename_bin2str(BinKey),
@@ -183,7 +185,8 @@ put_begin(#dcerl_state{datadir_path      = DataDir,
         OnKeys2 = sets:add_element(BinKey, OnKeys),
         TmpDP = data_filename(DataDir, BinKey) ++ ?SUFFIX_TMP,
         {ok, TmpIoDev} = file:open(TmpDP, [write, raw, delayed_write]),
-        {ok, State#dcerl_state{ongoing_keys = OnKeys2},
+        {ok, State#dcerl_state{ongoing_keys       = OnKeys2,
+                               tmp_datafile_iodev = TmpIoDev},
          #dcerl_fd{key                = BinKey,
                    tmp_datafile_iodev = TmpIoDev}}
     catch
@@ -194,14 +197,18 @@ put_begin(#dcerl_state{datadir_path      = DataDir,
                                     {line, ?LINE},
                                     {body, Reason}]),
             {error, Reason}
-    end.
+    end;
+put_begin(_State, _Key) ->
+    {error, conflict}.
 
 %%
 %% @doc Put a chunk into the specified leo_dcerl erlang process while doing transaction
 -spec(put_chunk(State, Fd, Chunk) ->
              ok|{error, any()} when State::#dcerl_state{},
-                                    Fd::#dcerl_fd{},
+                                    Fd::#dcerl_fd{}|undefined,
                                     Chunk::binary()).
+put_chunk(_State, undefined, _Chunk) ->
+    {error, undefined};
 put_chunk(_State, #dcerl_fd{tmp_datafile_iodev = TmpIoDev} = _Fd, Chunk) ->
     file:write(TmpIoDev, Chunk).
 
@@ -210,9 +217,11 @@ put_chunk(_State, #dcerl_fd{tmp_datafile_iodev = TmpIoDev} = _Fd, Chunk) ->
 %%      into the specified leo_dcerl erlang process
 -spec(put_end(State, Fd, CM, Commit) ->
              {ok, #dcerl_state{}}|{error, any()} when State::#dcerl_state{},
-                                                      Fd::#dcerl_fd{},
+                                                      Fd::#dcerl_fd{}|undefined,
                                                       CM::#cache_meta{},
                                                       Commit::boolean()).
+put_end(_State, undefined, _CM, _Commit) ->
+    {error, undefined};
 put_end(#dcerl_state{cache_entries     = CE,
                      cache_stats       = CS,
                      datadir_path      = DataDir,
@@ -261,6 +270,7 @@ put_end(#dcerl_state{cache_entries     = CE,
         PrevSize = CS#cache_stats.cached_size,
         PrevRec  = CS#cache_stats.records,
         NewState = State#dcerl_state{
+                     tmp_datafile_iodev = undefined,
                      redundant_op_cnt = OpCnt + 1,
                      ongoing_keys     = OnKeys2,
                      cache_metas      = Metas2,
@@ -293,6 +303,7 @@ put_end(#dcerl_state{datadir_path      = DataDir,
     OnKeys2 = sets:del_element(BinKey, OnKeys),
 
     {ok, State#dcerl_state{
+           tmp_datafile_iodev = undefined,
            redundant_op_cnt = OpCnt + 1,
            ongoing_keys     = OnKeys2}}
     catch

src/leo_dcerl_server.erl

@@ -20,7 +20,7 @@
 %%
 %% ---------------------------------------------------------------------
 %% DCerl Server
-%% @doc
+%% @doc The disc cache's server
 %% @end
 %%======================================================================
 -module(leo_dcerl_server).
@@ -52,8 +52,7 @@
 %%--------------------------------------------------------------------
 %% API
 %%--------------------------------------------------------------------
-%% Function: {ok,Pid} | ignore | {error, Error}
-%% Description: Starts the server.
+%% @doc Starts the server.
 -spec(start_link(Id, DataDir, JournalDir, CacheSize, ChunkSize) ->
              'ignore' | {'error',_} | {'ok',pid()} when Id::atom(),
                                                         DataDir::string(),
@@ -65,15 +64,13 @@ start_link(Id, DataDir, JournalDir, CacheSize, ChunkSize) ->
                           [DataDir, JournalDir, CacheSize, ChunkSize], []).
 
 
-%% Function: -> ok
-%% Description: Manually stops the server.
+%% @doc Manually stops the server.
 -spec(stop(Pid) -> ok when Pid::atom()).
 stop(Pid) ->
     gen_server:cast(Pid, stop).
 
 
 %% @doc Retrieve a reference
-%%
 -spec(get_ref(Id, Key) ->
              undefined | binary() | {error, any()} when Id::atom(),
                                                         Key::binary()).
@@ -82,23 +79,20 @@ get_ref(Id, Key) ->
 
 
 %% @doc Retrieve a value associated with a specified key
-%%
 -spec(get(Id, Key) ->
              undefined | binary() | {error, any()} when Id::atom(),
                                                         Key::binary()).
 get(Id, Key) ->
     gen_server:call(Id, {get, Key}).
 
 %% @doc Retrieve a value associated with a specified key
-%%
 -spec(get_filepath(Id, Key) ->
              undefined | #cache_meta{} | {error, any()} when Id::atom(),
                                                              Key::binary()).
 get_filepath(Id, Key) ->
     gen_server:call(Id, {get_filepath, Key}).
 
 %% @doc Retrieve a value associated with a specified key
-%%
 -spec(get(Id, Ref, Key) ->
              undefined | binary() | {error, any()} when Id::atom(),
                                                         Ref::any(),
@@ -108,7 +102,6 @@ get(Id, Ref, Key) ->
 
 
 %% @doc Insert a key-value pair into the leo_dcerl
-%%
 -spec(put(Id, Key, Value) ->
              ok | {error, any()} when Id::atom(),
                                       Key::binary(),
@@ -176,6 +169,7 @@ size(Id) ->
 %%====================================================================
 %% GEN_SERVER CALLBACKS
 %%====================================================================
+%% @doc Initiates the server
 init([DataDir, JournalDir, CacheSize, ChunkSize]) ->
     case leo_dcerl:start(DataDir, JournalDir, CacheSize, ChunkSize) of
         {ok, Handler} ->
@@ -185,6 +179,8 @@ init([DataDir, JournalDir, CacheSize, ChunkSize]) ->
             {stop, Cause, null}
     end.
 
+
+%% @doc gen_server callback - Module:handle_call(Request, From, State) -> Result
 handle_call({get_ref, Key}, _From, #state{handler = Handler} = State) ->
     {Res, NewState} =
         case catch leo_dcerl:get(Handler, Key) of
@@ -359,13 +355,15 @@ handle_call({put_end_tran, Ref, _Key, Meta, IsCommit}, _From, #state{handler = H
                                        [{module, ?MODULE_STRING},
                                         {function, "handle_call/3"},
                                         {line, ?LINE}, {body, Cause}]),
-                {{error, Cause}, State};
+                Handler3 = Handler#dcerl_state{tmp_datafile_iodev = undefined},
+                {{error, Cause}, State#state{handler = Handler3}};
             {error, Cause} ->
                 error_logger:error_msg("~p,~p,~p,~p~n",
                                        [{module, ?MODULE_STRING},
                                         {function, "handle_call/3"},
                                         {line, ?LINE}, {body, Cause}]),
-                {{error, Cause}, State}
+                Handler3 = Handler#dcerl_state{tmp_datafile_iodev = undefined},
+                {{error, Cause}, State#state{handler = Handler3}}
         end,
     {reply, Res, NewState};
 
@@ -422,29 +420,34 @@ handle_call({size}, _From, #state{handler = Handler} = State) ->
 handle_call(_Request, _From, State) ->
     {reply, undefined, State}.
 
+
+%% @doc Handling cast message
+%% <p>
+%% gen_server callback - Module:handle_cast(Request, State) -> Result.
+%% </p>
 handle_cast(stop, State) ->
     {stop, normal, State};
 
 handle_cast(_Msg, State) ->
     {noreply, State}.
 
+
+%% @doc Handling all non call/cast messages
+%% <p>
+%% gen_server callback - Module:handle_info(Info, State) -> Result.
+%% </p>
 handle_info(_Info, State) ->
     {noreply, State}.
 
 
-%% ----------------------------------------------------------------------------------------------------------
-%% Function: terminate(Reason, State) -> void()
-%% Description: This function is called by a gen_server when it is about to terminate. When it returns,
-%% the gen_server terminates with Reason. The return value is ignored.
-%% ----------------------------------------------------------------------------------------------------------
+%% @doc This function is called by a gen_server when it is about to
+%%      terminate. It should be the opposite of Module:init/1 and do any necessary
+%%      cleaning up. When it returns, the gen_server terminates with Reason.
 terminate(_Reason, _State) ->
     terminated.
 
 
-%% ----------------------------------------------------------------------------------------------------------
-%% Function: code_change(OldVsn, State, Extra) -> {ok, NewState}
-%% Description: Convert process state when code is changed.
-%% ----------------------------------------------------------------------------------------------------------
+%% @doc Convert process state when code is changed
 code_change(_OldVsn, State, _Extra) ->
     {ok, State}.
 

src/leo_dcerl_sup.erl

@@ -50,7 +50,6 @@
 %%-----------------------------------------------------------------------
 %% External API
 %%-----------------------------------------------------------------------
-%% @spec (Params) -> ok
 %% @doc start link.
 %% @end
 start_link() ->
@@ -63,8 +62,6 @@ start_link() ->
     supervisor:start_link({local, ?MODULE}, ?MODULE, [TotalCacheSize]).
 
 
-%% @spec () -> ok |
-%%             not_started
 %% @doc stop process.
 %% @end
 stop() ->
@@ -79,7 +76,6 @@ stop() ->
 %% ---------------------------------------------------------------------
 %% Callbacks
 %% ---------------------------------------------------------------------
-%% @spec (Params) -> ok
 %% @doc stop process.
 %% @end
 %% @private

test/leo_dcerl_server_tests.erl

@@ -76,6 +76,7 @@ normal_test() ->
 
     %% Test - PUT#2
     {ok, Ref} = leo_dcerl_server:put_begin_tran(Id, BinKey),
+    {error, conflict} = leo_dcerl_server:put_begin_tran(Id, BinKey),
     Chunk = data_block(Src, 128),
     ok = leo_dcerl_server:put(Id, Ref, BinKey, Chunk),
     ok = leo_dcerl_server:put(Id, Ref, BinKey, Chunk),