anchor.diff:  = futura - The building blocks for asynchronous programming in Clojure.
   Andrey Antukh, <niwi@niwi.be>
   :toc: left
  +:toclevels: 1
   :numbered:
   :source-highlighter: pygments
   :pygments-style: friendly
  
positive.code: 
  == Introduction
  
  TBD
  
  == Rationale
  
  TBD
  
  
  == Project Maturity
  
negative.code: ----
  
  
  == Promises
  
  TBD
  
  
  == Streams
  
  The streams in _futura_ library are governed by the 
  link:http://www.reactive-streams.org/[reactive streams] iniciative and its default interfaces
  for the jvm languages but with support for the powerful clojure's features as transducers and sequence
  abstractions.
  
  TBD
  
  
  == Atomics
  
  This is a simple clojure friendly syntax and lightweight abstraction built on top of clojure's protocols
  for treat with JDK atomic types and reference types.
  
  This is a low level, side effecting primitive and should be used only when you are really known that
  are you doing. If you do not know if you should use it or not, prefer using standard clojure primitives
  such as atom, ref, and agents.
  
  
  === Atomic Reference
  
  The atomic reference privides a lock-free, thread safe object reference container. The real purpose
  of this type is store a reference to an arbitrary object and will be able mutate it in a thread
  safe, lock-fre way.
  
  ==== Creating an atomic reference
  
  The atomic reference can be created with `ref` function from the `futura.atomic` namespace:
  
  [source, clojure]
  ----
  (require '[futura.atomic :as atomic])
  
  (atomic/ref :foo)
  ;; => #object[futura.atomic.AtomicRef 0x5e42bd13 {:status :ready, :val :foo}]
  ----
  
  //^ And it accepts different kind of typical operatons of atomic abstractions:
  
  ==== Get and set values
  
  The atomic reference provides the standard way to set or get values using `get` and `set!` functions:
  
  [source, clojure]
  ----
  (atomic/set! myref :baz)
  
  (atomic/get myref)
  ;; :baz
  ----
  
  Additionally it also implements the clojure `IDeref` interface for make it easy use with `@` reader
  macro or `deref` function:
  
  [source, clojure]
  ----
  (def myref (atomic/ref :foo))
  
  (deref myref)
  ;; => :foo
  
  @myref
  ;; => :foo
  ----
  
  
  ==== Special operations
  
  The atomic types usually offers some special operations, and this one is not an exception. The atomic
  refernce allow CAS operations (compare and set):
  
  [source, clojure]
  ----
  (atomic/compare-and-set! myref :baz :foobar)
  ;; => false
  
  (atomic/compare-and-set! myref :foo :bar)
  ;; => true
  ----
  
  And the "get and set" operation:
  
  [source, clojure]
  ----
  (atomic/get-and-set! myref :foo)
  ;; => :bar
  
  @myref
  ;; => :foo
  ----
  
  Additionaly it provides a way to set a value in some kind of "asynchronously" way. But take care, this
  method to set the value does not guarrantee that the change is visible instantly to all threads:
  
  [source, clojure]
  ----
  (atomic/eventually-set! myref :foobar)
  ----
  
  ==== Atom like interface
  
  Additionally, it already implements some convenient clojure abstractions such as:
  
  .Atom like access with `swap!` and `reset!`:
  [source, clojure]
  ----
  TBD
  ----
  
  .Watchers support:
  [source, clojure]
  ----
  TBD
  ----
  
  === Atomic Boolean
  
  This is a specialized version of Atomic Reference that is higtly optimized for boolean values. It
  has the same operations and implements the same abstractions that previously explained atomic ref.
  
  You can create an atomic boolean using `boolean` function from `futura.atomic` namespace:
  
  [source, clojure]
  ----
  (atomic/boolean false)
  ;; => #object[futura.atomic.AtomicBoolean 0x393bbfce {:status :ready, :val false}]
  ----
  
  === Atomic Long
  
  TBD
  
  