===
dtm
===

Distributed transaction management tools for PostgreSQL.

--------------------
Communication scheme
--------------------

      .- Backend -.
     /             \
    /               \
DTM ---- Backend ---- Coordinator
    \               /
     \             /
      `- Backend -´

-----------------------
Coordinator-Backend API
-----------------------

This API includes a set of postgres procedures that
the coordinator can call with "select" statement.

extend_transaction (n integer) -> (higcid gcid)
join_transaction (higcid gcid) -> ()
FIXME: add procedures that would start and finish 2pc

----------
libdtm api
----------

typedef unsigned long long cid_t;

// Connects to the specified DTM.
DTMConn DtmConnect(char *host, int port);

// Disconnects from the DTM. Do not use the 'dtm' pointer after this call, or
// bad things will happen.
void DtmDisconnect(DTMConn dtm);

// Asks DTM for the first 'gcid' with unknown status. This 'gcid' is used as a
// kind of snapshot. Returns the 'gcid' on success, or INVALID_GCID otherwise.
cid_t DtmGlobalGetNextCid(DTMConn dtm);

// Prepares a commit. Returns the 'gcid' on success, or INVALID_GCID otherwise.
cid_t DtmGlobalPrepare(DTMConn dtm);

// Finishes a given commit with 'committed' status. Returns 'true' on success,
// 'false' otherwise.
bool DtmGlobalCommit(DTMConn dtm, cid_t gcid);

// Finishes a given commit with 'aborted' status.
void DtmGlobalRollback(DTMConn dtm, cid_t gcid);

// Gets the status of the commit identified by 'gcid'. Returns the status on
// success, or -1 otherwise.
int DtmGlobalGetTransStatus(DTMConn dtm, cid_t gcid);

--------------------
Backend-DTM Protocol
--------------------

DTM <--> Backend:

<-   'p'<hex16 self> - "prepare"
  -> '+'<hex16 gcid> - "commit prepared"
  -> '-'             - "something went wrong"

<-   'c'<hex16 gcid> - "commit"
  -> '+'             - "commit saved"
  -> '-'             - "something went wrong"

<-   'a'<hex16 gcid> - "abort"
  -> '+'             - "abort saved"
  -> '-'             - "something went wrong"

<-   'h'             - "horizon"
  -> '+'<hex16 gcid> - "here is a gcid you can use as a snapshot"
  -> '-'             - "something went wrong"

<-   's'<hex16 gcid> - "status"
  -> '+''c|a|?'      - "here is the transaction status"
                       (c)ommitted, (a)borted or (?)unknown
  -> '-'             - "something went wrong"

Backend disconnection is considered as an abort of all incomplete commits
prepared by that backend.