persistent-map: A thread-safe (STM) persistency interface for finite map types.

[ concurrency, deprecated, library, middleware ] [ Propose Tags ]
Deprecated in favor of tbox

Changes in 0.3.*:

  • Added the TFiniteMap type to make type construction more convenient.

  • Added markAsDirty.

  • Fixed data corruption issues with Backend.Binary.

Changes in 0.2.*:

  • Improved error handling. Backend lookup-exceptions are now rethrown in the AdvSTM monad.

Changes in 0.1.*:

  • Added the binary serialization backend.

This library provides a thread-safe (STM) frontend for finite map types together with a backend interface for persistent storage. The TMap data type is thread-safe, since all access functions run inside an STM monad . Any type instantiating Data.Edison.Assoc.FiniteMapX (see EdisonAPI) can be used as a map type.

When a TMap is modified within an STM transaction, a corresponding backend IO-request is added using the onCommit hook (cf. stm-io-hooks package). To ensure consistency, the (Adv)STM monad runs these requests iff the transaction commits. Additional backends (e.g. HDBC) can be added by instantiating the class Backend.


Thread 1:

atomically $ do
  isMemb <- member 1 tmap
  when (not isMemb) $
    insert 1 "john doe" tmap

Thread 2:

atomically $ do
  v <- lookup 1 tmap
  -- ... do something with 'v'
  adjust (\_ -> "jd") 1 tmap

The function member will first check whether the key value '1' is in the map; if not, it sends a lookup-request to the persistent backend and then retries the transaction. Note that "sending a lookup-request" essentially means adding a call to the corresponding IO-function of the backend to the list of retry-IO actions. (This is done using the retryWith IO hook of the stm-io-package.)

If the value does not yet exist, function insert adds the key-value mapping to the TMap and sends an insert-request to the backend using the onCommit hook of the stm-io-package. Note that onCommit guarantees that the backend IO action is only executed iff the transaction commits. Any changes that were made to the TMap are invisible to other threads until the onCommit actions are run. Therefore, the threads will always observe a consistent state.

The module Data.TStorage provides a high level interface to TMap inspired by the TCache package ((C) Alberto Gomez Corona). It can store any type that has a key (i.e. is an instance of type class HasKey). See file Sample.hs for an example on how to use it.

Warning: This package is very experimental and the interface will probably change.


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


  • No Candidates
Versions [RSS] 0.0.0, 0.1.0, 0.1.1, 0.2.2, 0.3.3, 0.3.4, 0.3.5
Dependencies base (>=4 && <5), binary (>=0.5 && <0.6), containers (>= && <0.3), directory (>= && <1.1), EdisonAPI (>=1.2.1 && <1.3), EdisonCore (>= && <1.3), filepath (>=1.1 && <1.2), LRU (>=0.1.1 && <0.2), mtl (>= && <1.2), stm-io-hooks (>=0.4.0 && <0.5) [details]
License LicenseRef-LGPL
Author Peter Robinson 2009
Maintainer Peter Robinson <>
Category Middleware, Concurrency
Home page
Uploaded by PeterRobinson at 2009-08-06T07:03:05Z
Reverse Dependencies 1 direct, 0 indirect [details]
Downloads 5602 total (10 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user
Build status unknown [no reports yet]