File jc-1.2.1-git.patch of Package jc
diff --git a/README.md b/README.md
index 02fc1e7..1e3d06e 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,15 @@
JC
====
-##Erlang, Distributable, In-Memory Cache
+## Erlang, Distributable, In-Memory Cache
-### Featruing: Pub/Sub, JSON-query, consistency support, and a simple, TCP interop. protocol.
+### Featuring: Pub/Sub, JSON-query, consistency support, and a simple, TCP interop. protocol.
[](https://travis-ci.org/jr0senblum/jc)
[](https://hex.pm/packages/jc)
-###Features
+### Features
* Cache entries are Map, Key, Value, [TTL], [Sequence]
* Maps represent a name-space for Keys - similar to the notion
of 'bucket'
@@ -52,7 +52,7 @@ JC
broadcast arbitrary messages under those topic names
* Clients can subscribe to node-up and node-down events
* Interopability
- * Binary string over TCP returning JSON
+ * Binary string over TCP returning JSON (EXPERIMENTAL)
* Bridge process that accepts messages from a client indicating
cache operations, executes the cache operations and returns the
results to the client. This has been used with JInterface to
@@ -61,7 +61,7 @@ JC
-###Cache Functions (jc)
+### Cache Functions (jc)
* Create
* put(Map, Key, Value, [TTLSecs]) -> {ok, Key} | {error, badarg}
* put_all(Map, [{K,V},{K,V},...], [TTLSecs]) -> {ok, CountOfSuccessfulPuts} |
@@ -114,12 +114,12 @@ Identical to the Create and Evict family of functions of the jc module
-###Eviction Manager Functions (jc_eviction_manager)
+### Eviction Manager Functions (jc_eviction_manager)
* set_max_ttl(Map, Secs) -> ok | {error, badarg}
* get_max_ttls() -> [{Map, Secs}, ...]
-###Pub/Sub Functions (jc_psub)
+### Pub/Sub Functions (jc_psub)
* map_subscribe(Pid, Map, Key|any, write|delete|any) -> ok | {error, badarg}
* map_unsubscribe(Pid, Map, Key|any, write|delete|any) -> ok | {error, badarg}
* client receives
@@ -142,7 +142,7 @@ Identical to the Create and Evict family of functions of the jc module
`{jc_node_events, {nodeup, UppedNode, [ActiveNodes],[ConfiguredNodes]}}`
-###Indexing Functions (jc_store)
+### Indexing Functions (jc_store)
* start_indexing(Map, Path={bed,"menu.id"}) -> ok |
{error, no_indexes_available} |
{error, Term}
@@ -152,7 +152,7 @@ Identical to the Create and Evict family of functions of the jc module
* indexes() -> {indexes, [{{Map, Path}, Position},...]} for all indexes
-###Interoperability: Bridge (jc_bridge)
+### Interoperability: Bridge (jc_bridge)
* All functions from the jc, jc_s, jc_eviction_manager, jc_psub
and jc_store are supported and are of the form:
@@ -176,7 +176,7 @@ Identical to the Create and Evict family of functions of the jc module
{From, {node_topic_unsub}} -> ok.
-### Interoperability: Socket Protocol - EXPIREMENTAL
+### Interoperability: Socket Protocol - EXPERIMENTAL
Binary-encoded, string protocol used to provide socket-based
interoperability with JC.
@@ -236,13 +236,13 @@ might look as follows:
-###Configuration
+### Configuration
* Application configuration is in sys.config which is heavily
commented
* Cookie, node-name and auto-restart of VM controlled by vm.args
-###Application Modules
+### Application Modules
* jc_cluster
* Simple, mnesia-based, cluster creation and management
* jc, jc_s, jc_store, jc_eviction_manager
@@ -266,7 +266,7 @@ might look as follows:
* Looks for evidence of node dis/apperation and implements a recovery
strategy
-###Net Split/Join Strategy
+### Net Split/Join Strategy
Mnesia does not merge on its own when a node joins (returns) to a mesh of nodes.
There are two situations where this is relevant:
@@ -289,7 +289,7 @@ Given this ClusterId, we have the following strategy:
restarted by the hearbeat application. If any Nodes required restarting, the entire
cache is flushed.
-###Build Instructions
+### Build Instructions
* Ensure that Erlang 17 or higher is installed
* Get the Source Code from Stash
@@ -306,7 +306,7 @@ Given this ClusterId, we have the following strategy:
`[root@db01] ./rebar3 as prod release`
-###Documentation
+### Documentation
`[root@dbo1] ./rebar3 edoc`
diff --git a/config/sys.config b/config/sys.config
index 34dbd78..b1e056d 100644
--- a/config/sys.config
+++ b/config/sys.config
@@ -1,9 +1,9 @@
-%% Typically the only line that is customer specific is the cache_nodes lines in
+%% Typically the only line that are customer specific are the cache_nodes lines in
%% the jc stanza.
[
- %% SASL config - type of logging not typically used, but might come in handy
- %% log files will be created, but are small and rotated.
+ %% SASL config - not typically used, but might come in handy. Log files will be
+ %% created, but are small and rotated.
{sasl, [
{sasl_error_logger, {file, "log/sasl-error.log"}},
{errlog_type, error},
@@ -15,21 +15,20 @@
{mnesia,
[
%% Specifies the maximum number of writes allowed to the transaction log
- %% before a new dump of the log is performed. The higer the more ram is
- %% used but low numbers may result in mnesia not being able to keep up.
+ %% before a new dump of the log is performed. The higer the more RAM is
+ %% used, but low numbers may result in mnesia not being able to keep up.
%% Default is 100
{dump_log_write_threshold, 50000},
- %% Must be ram so that schema is diskless. This allows for nodes to come in
- %% and out of the cluster in any order without worying about conflicting
+ %% MUST be RAM so that schema is diskless. This allows for nodes to come
+ %% in and out of the cluster in any order without worying about conflicting
%% masters.
{schema_location, ram}
- ]
- },
-
+ ]},
{lager,
[
+ %% Lager back-end handlers. Logs are small and rotated by default.
{handlers, [
{lager_console_backend, info},
{lager_file_backend, [{file, "log/error.log"},
@@ -37,19 +36,18 @@
{size, 10485760},
{date, "$D0"},
{count, 5}]},
-%% Uncomment for file-based debug log
-%% {lager_file_backend, [{file, "log/debug.log"},
-%% {level, debug},
-%% {size, 10485760},
-%% {date, "$D0"},
-%% {count, 5}]},
+ %% Uncomment for file-based debug log
+ %% {lager_file_backend, [{file, "log/debug.log"},
+ %% {level, debug},
+ %% {size, 10485760},
+ %% {date, "$D0"},
+ %% {count, 5}]},
{lager_file_backend, [{file, "log/info.log"},
{level, info},
{size, 10485760},
{date, "$D0"},
{count, 5}]}
]},
- %% We are not racist and do not want colors on the command line.
{colored, true}
]},
@@ -63,7 +61,9 @@
{table_wait_ms, 2000},
%% At what interval to run the process that looks for clients with no
- %% subscriptions and remove them from the subscriber (ps_client) tables.
+ %% subscriptions and removes them from the subscriber (ps_client) tables.
+ %% This is a safety-net activity and is used to remove subscriptions that
+ %% failed to be removed due to a failure of somesort.
{evict_deadbeats_ms, 3600000},
%% How often to run the process that evicts records that are older than the
@@ -71,16 +71,18 @@
{max_ttl_job_secs, 180},
%% Possibly empty list indicating max_ttl for records in the map. Format is
- %% {max_ttl_maps, [{Map1, Secs1}]},
+ %% {max_ttl_maps, [{Map1, Secs1}, ..., {MapN, SecsN}]},
{max_ttl_maps, [{testmap, 100}]},
- %% Initial json values upon which to index
+ %% Initial JSON values upon which to index. In a path, the number 2 indicates
+ %% the second whatever, while the '2' indicates the string 2 in the path.
%% {indexes, [{bed, "identifier"}, {bed, "menu.2.id.'2'"}]}
- %% Frequency needed to warrant indexing {freq, Time_secs}
+ %% Frequency needed to see a particular JSON query before indexing
+ %% {freq, Time_secs}
{analyze_freq, {5, 5}},
- %% Port for the Socket protocol listener
+ %% Port for the Socket protocol listener EXPIRAMENTAL FEATURE
{protocol_port, 5555}
]}
diff --git a/include/records.hrl b/include/records.hrl
index 0e5398e..f3e094b 100644
--- a/include/records.hrl
+++ b/include/records.hrl
@@ -1,22 +1,21 @@
% Types
-type seconds() :: non_neg_integer().
+-type ttl() :: seconds().
+-type time_stamp() :: seconds().
-type map_name() :: any().
-type key() :: any().
-type value() :: any().
--type ttl() :: seconds().
+
-type rec_ref() :: reference().
--type time_stamp() :: seconds().
-% Key_to_value - an ordered_set table whose key is {key, map}. Ref is used by
-% jc_eviction manager as the key of the cache item to evict. i1 - i4 are
-% fields that can be used to hold values pulled from a json value to support a
-% querry-select feature (see README and jc_store:start_indexing/2 for more. Seq
-% is an integer supplied by the client that, if provided, is expected to be
-% strictly monotinic. If it is not, the put with the non monotonic value will
-% be evicted and the old one re-inserted.
-%
+
+% Key_to_value - an ordered_set table whose key is {key, map_name}. Ref is used
+% by jc_eviction manager as the key of the cache item to evict. i1 - i4 are
+% fields that can be used to hold values pulled from a json value to support an
+% indexed querry-select feature (see README and jc_store:start_indexing/2 for
+% more).
-record (key_to_value,
{jc_key :: {key(), map_name()},
map :: map_name(),
@@ -35,14 +34,19 @@
-type key_to_value() :: #key_to_value{}.
+% Seq_no is an integer supplied by the client that, if provided, MUST be
+% strictly monotinic and is used as a sequence number to ensure that a stale
+% operation doesn't make it to jcache after the fact and clobber a more recent
+% put or evict operation.
-record(seq,
{map :: map_name(),
seq_no :: jc_sequence:seq()
}).
-% Holds information about json-path's that will be the target of a query-sellect
-% for a given map. Position indicates which column (i1-i4) in key_to_value to
-% use.
+
+% Defines the index for a given map and JSON path. Used for query-selects and
+% evicts. Position indicates which column (i1-i4) in key_to_value to store the
+% index.
-record (to_index,
{map_path :: {map_name(), tuple()},
map_name :: map_name(),
@@ -50,6 +54,8 @@
}).
+% Record that keeps track of the accounting around a JSON query as part of
+% determining whether an index should be initiatied.
-record (auto_index,
{map_path :: {map_name(), tuple()} | '_',
count :: non_neg_integer() | '_',
@@ -86,7 +92,6 @@
}).
-
% Jc_psub records. Subscription patterns and the set of PIDS subscribed to those
% patterns.
-record (ps_sub,
@@ -94,6 +99,7 @@
clients = sets:new() :: sets:set()
}).
+
% Ps_client records. Unique processes that are subscribers, includings what type
% of mechanism is used to monitor the client - link to the Pid or monitor the
% node.
diff --git a/rebar.config b/rebar.config
index 4706976..1322997 100644
--- a/rebar.config
+++ b/rebar.config
@@ -12,7 +12,7 @@
{deps, [
{jwalk, "1.1.0"},
{jsone, "1.2.0"},
- {lager, "3.2.1"},
+ {lager, "3.2.4"},
{ranch, "1.1.0"}
]}.
diff --git a/rebar.lock b/rebar.lock
index 69812fa..7178328 100644
--- a/rebar.lock
+++ b/rebar.lock
@@ -1,5 +1,5 @@
-[{<<"goldrush">>,{pkg,<<"goldrush">>,<<"0.1.7">>},1},
+[{<<"goldrush">>,{pkg,<<"goldrush">>,<<"0.1.9">>},1},
{<<"jsone">>,{pkg,<<"jsone">>,<<"1.2.0">>},0},
{<<"jwalk">>,{pkg,<<"jwalk">>,<<"1.1.0">>},0},
- {<<"lager">>,{pkg,<<"lager">>,<<"3.0.1">>},0},
+ {<<"lager">>,{pkg,<<"lager">>,<<"3.2.4">>},0},
{<<"ranch">>,{pkg,<<"ranch">>,<<"1.1.0">>},0}].
diff --git a/src/jc.erl b/src/jc.erl
index abb791d..e22124c 100644
--- a/src/jc.erl
+++ b/src/jc.erl
@@ -1,14 +1,15 @@
%%% ----------------------------------------------------------------------------
%%% @author Jim Rosenblum
-%%% @copyright (C) 2011 - 2015, Jim Rosenblum
+%%% @copyright (C) 2011 - 2017, Jim Rosenblum
%%% @doc This module wraps the mnesia-interacting, lower-level functions
%%% implemented in {@link jc_store. jc_store} to provide a public, DIRTY,
%%% set of opperations. {@link jc_s. jc_s} provides functions that take a
%%% sequence parameter to better support serilization (consistency) without.
%%% resorting to transactions.
%%%
-%%% JC can be called directly by Erlang clients; or,
+%%% The jc module can be called directly by Erlang clients; or,
%%% Java node -> JInterface -> {@link jc_bridge. jc_bridge} -> jc; or,
+%%% experimentally,
%%% Application -> TPC/IP -> {@link jc_protocol. jc_protocol} -> jc
%%%
%%% @version {@version}
@@ -29,7 +30,6 @@
flush/0, flush/1,
remove_items/2]).
-
% Get Functions
-export([contains_key/2,
get/2,
@@ -38,8 +38,11 @@
values/1,
values_match/2]).
-% CACHE META-INFO SUPPORT
--export([cache_nodes/0, cache_size/0, map_size/1, maps/0, up/0, stop/0]).
+% Control
+-export([stop/0]).
+
+% Cache Meta-data support
+-export([cache_nodes/0, cache_size/0, map_size/1, maps/0, up/0]).
% Used by jc_s for evict_match
-export([fun_match/3]).
@@ -47,18 +50,18 @@
% Used by eviction manager to evict an entry based on a reference
-export ([delete_record_by_ref/1]).
-
% definitions of global records and types.
-include("../include/records.hrl").
+% ttl is either infinity (0) or an integer > 0.
-define(INFINITY, 0).
-define(VALID(X), is_integer(X) andalso (X >= 0)).
%% =============================================================================
-%% Meta data API
+%% Cache control
%% =============================================================================
@@ -75,6 +78,12 @@ stop()->
ok.
+
+%% =============================================================================
+%% Meta data API
+%% =============================================================================
+
+
%% -----------------------------------------------------------------------------
%% @doc Return a sorted list of all maps currently in the cache.
%%
