n4u
/
kvs


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322
							<html>

<head>
    <meta charset="utf-8" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="description" content="" />
    <meta name="author" content="Maxim Sokhatsky" />
    <title>STREAM</title>
    <link rel="stylesheet" href="https://n2o.space/n2o.css" />
</head>

<body>

<header>
    <a href="../index.html"><img src="https://n2o.space/img/Synrc Neo.svg"></a>
    <h1>STREAM</h1>
</header>

<main>
    <section>

<h3>INTRO</h3>

<p>The <b>kvs_stream</b> is intended to store and retrieve doubly-linked lists
   using simple key-value access to different databases through its backends:
   redis, mongo, mnesia, riak, kai, fs.
   The main KVS cursor consist of two main parts (reader and writer).
   Writer holds the cached value of the top or bottom of the stream.
   Reader holds the cached valus of current cursor position.
   Descriptor also tracks moving direction and distances to both ends,
   which are updated during reader cursor repositioning.
   Cursor should be stored in databse.
   If there is no cursor for some data then this data is not alive yet.
   The data could be added only to list ends using writer cursor.
   The data in list could be removed only by record id.
   The list could not contain duplicates or even records with the same id.
   When you consume the stream, the data is not deleted.</p>
    </section>
    <section>

<h3>RECORDS</h3>

<figure><figcaption>KVS CORE</figcaption><code>
    #ok { data= [] :: term() }.

 #error { data= [] :: term() }.

   #cur { id=   [] :: term(),
          top=  [] :: [] | integer(),
          bot=  [] :: [] | integer(),
          dir=   0 ::  0 | 1,
          pos=  [] :: [] | tuple(),
          val=  [] :: [] | tuple()  }.

  #iter { id=   [] :: [] | integer(),
          prev= [] :: [] | integer(),
          next= [] :: [] | integer()).

</code></figure>

<p><ul>
<li>id &mdash; Unique key of the cursor</li>
<li>val &mdash; Writer cursor.</li>
<li>pos &mdash; Reader cursor.</li>
<li>dir=0 &mdash; Adding to top, reading up from bottom (default).</li>
<li>dir=1 &mdash; Adding to bottom, reading down from top.</li>
<li>top &mdash; The top of the list</li>
<li>bot &mdash; The bottom of the list</li>
</ul></p>

<p><ul>
<li>id &mdash; Unique key of the record in the list</li>
<li>next &mdash; The next element of the list</li>
<li>prev &mdash; The prev element of the list</li>
</ul></p>

    </section>
    <section>

<h3>EXAMPLE</h3>

<figure><code>
 -module(test).
 -include_lib("kvs/include/kvs.hrl").
 -include_lib("kvs/include/user.hrl").
 -compile(export_all).

 check() ->
     Cur = kvs_stream:new(),
     [A,B,C,D] = [ kvs:next_id(person,1)
              || _ <- lists:seq(1,4) ],
     R = kvs_stream:save(
         kvs_stream:add(#person{id=A},
         kvs_stream:add(#person{id=B},
         kvs_stream:add(#person{id=C},
         kvs_stream:add(#person{id=D}, Cur ))))),
     X = kvs_stream:take(-1,
         kvs_stream:down(
         kvs_stream:top(R))),
     Y = kvs_stream:take(-1,
         kvs_stream:up(
         kvs_stream:bot(R))),
     X = lists:reverse(Y),
     L = length(X).

 > test:check().
 4

 > kvs:all(cur).
 [{cur,1,{user2,1,3,[],[],[],[],[],[]},0,1,2}]

 > kvs_stream:take(-1,
   kvs_stream:top(kvs:get(cur,1))).
[{user2,2,[],4,[],[],[],[],[]},
 {user2,4,2,3,[],[],[],[],[]},
 {user2,3,4,1,[],[],[],[],[]},
 {user2,1,3,[],[],[],[],[],[]}]

</code></figure>
    </section>
    <section>

<h3>API</h3>

<p>We prepared for you sequential steps manual.
   Just enter the erlang commands in shell in right order
   and check the results.

<h4>new() -> #cur{}.</h4>

<p>Creates a KVS cursor.</p>

<figure><code>
 > kvs_stream:new().
 {cur,1,[],0,[],[]}
 > kvs:get(id_seq,"cur").
 {ok,{id_seq,"cur",1}}
 > kvs_stream:new().
 {cur,2,[],0,[],[]}
 > kvs:get(id_seq,"cur").
 {ok,{id_seq,"cur",2}}

</code></figure>

<h4>save(#cur{}) -> #cur{}.</h4>

<p>Saves the cursor to database.<?p>

<figure><code>
 > kvs:all(cur).
 []
 > kvs_stream:save(kvs_stream:new()).
 {cur,3,[],0,[],[]}
 > kvs:all(cur).
 [{cur,3,[],0,[],[]}]

</code></figure>

<h4>load(Id) -> #ok{data::#cur{}} | #error{}.</h4>

<p>Gets a cursor from database.</p>

<figure><code>
  > S = 3, kvs_stream:load(S).
  {cur,3,[],[],0,[]}

</code></figure>

<h4>add(Message,#cur{}) -> #cur{}.</h4>

<p>Adds message to datatabase and update cursor to new data.
   Message is linked on next prev fields with existed data under cursor.
   If cursor doesn't contain top or bottom value the additional
   seek to the end is performed according to cursor direction.</p>

<figure><code>
 > rr(kvs_stream).
 [block,container,cur,id_seq,iter,iterator,kvs,log,operation]

 > P = {user2,[],[],[],[],[],[],[],[]},
   kvs_stream:save(kvs_stream:add(P,kvs_stream:load(S))).
 #cur{id = 3,top = 1,bot = 1,dir = 0,
      pos = {user2,1,[],[],[],[],[],[],[]},
      val = {user2,1,[],[],[],[],[],[],[]},
      left = 0,right = 0}

</code></figure>

<h4>prev(#cur{}) -> #cur{} | #error{}.</h4>

<p>Moves cursor to prev. Consume data bottom up.
   Reutrn error if lists is empty, otherwise next element or last.</p>

<figure><code>
 > kvs_stream:prev(kvs_stream:load(S)).
 {error,not_found}

</code></figure>

<h4>next(#cur{}) -> #cur{} | #error{}.</h4>

<p>Moves cursor to next. Consume data top down.
   Reutrn error if lists is empty, otherwise next element or last.</p>

<figure><code>
 > kvs_stream:next(kvs_stream:top(
   kvs_stream:save(kvs_stream:add(P,kvs_stream:load(S))))).
  #cur{id = 3,top = 2,bot = 1,dir = 1,
      pos = {user2,1,[],2,[],[],[],[],[]},
      val = {user2,2,1,[],[],[],[],[],[]},
      left = 0,right = 1}

</code></figure>

<h4>seek(#cur{}) -> #cur{} | #error{}.</h4>

<p>Moves cursor to begin or end of the list depending of cursor order.
   If cursor has no cached value then function returns error.</p>

<figure><code>
 > Stream = kvs_stream:save(kvs_stream:add(P,kvs_stream:load(S))),
   kvs_stream:seek(kvs_stream:up(Stream)).
 #cur{id = 3,top = 3,bot = 1,dir = 0,
      pos = {user2,1,[],2,[],[],[],[],[]},
      val = {user2,3,2,[],[],[],[],[],[]},
      left = 2,right = 0}

</code></figure>

<h4>top(#cur{}) -> #cur{} | #error{}.</h4>

<p>Moves cursor to top of the list.</p>

<figure><code>
 > kvs_stream:top(kvs_stream:load(S)).
 #cur{id = 3,top = 3,bot = 1,dir = 1,
     pos = {user2,3,2,[],[],[],[],[],[]},
     val = {user2,3,2,[],[],[],[],[],[]},
     left = 2,right = 0}

</code></figure>

<h4>bot(#cur{}) -> #cur{} | #error{}.</h4>

<p>Moves cursor to bottom of the list.</p>

<figure><code>
 > kvs_stream:bot(kvs_stream:load(S)).
 #cur{id = 3,top = 3,bot = 1,dir = 0,
      pos = {user2,1,[],2,[],[],[],[],[]},
      val = {user2,3,2,[],[],[],[],[],[]},
      left = 2,right = 0}

</code></figure>

<h4>take(N,#cur{}) -> list().</h4>

<p>Trying to consume N records from stream using its current value and direction.
   Returns consumed data. Usually you seek to some position and then consume some data.</p>

<figure><code>
 > kvs_stream:take(-1,kvs_stream:load(S)).
 [{user2,3,2,[],[],[],[],[],[]},
  {user2,2,1,3,[],[],[],[],[]},
  {user2,1,[],2,[],[],[],[],[]}]

</code></figure>

<h4>down(#cur{}) -> #cur{}.</h4>

<p>Changes the cursor direction.</p>

<h4>up(#cur{}) -> #cur{}.</h4>

<p>Changes the cursor direction.</p>

<h4>remove(Id,#cur{}) -> #cur{} | #error{}.</h4>

<p>Removes record by id from database and unlink it from list.
   If cursor has no cached value then function returns error.
   Please do not use remove, keep your data immutable :-)</p>

<figure><code>
 > kvs_stream:take(-1,kvs_stream:top(kvs_stream:save(
   kvs_stream:remove(Stream#cur.top-1,kvs_stream:load(S))))).
 [{user2,1,[],3,[],[],[],[],[]},
  {user2,3,1,[],[],[],[],[],[]}]

</code></figure>

    </section>
    <section>

<h3>CONFIG</h3>

<p>In sys.config you should specify kvs backend and list of modules
   containing <b>metainfo/0</b> exported function.</p>

<figure><code>
  [{kvs, [{dba, store_mnesia},
          {schema, [kvs]} ]}].

</code></figure>

    </section>
    <section>

<p>This module may refer to:
<a href="http://erlang.org/doc/man/mnesia.html">mnesia</a></b>,
<a href="kvs.htm"><b>kvs</b></a>.
</p>

    </section>
</main>

<footer>
    2005&mdash;2017 &copy; Synrc Research Center
</footer>

</body>
</html>