transaction_base.hxx

Go to the documentation of this file.

/*-------------------------------------------------------------------------
 *
 *   FILE
 *      pqxx/transaction_base.hxx
 *
 *   DESCRIPTION
 *      common code and definitions for the transaction classes.
 *   pqxx::transaction_base defines the interface for any abstract class that
 *   represents a database transaction
 *   DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/transaction_base instead.
 *
 * Copyright (c) 2001-2004, Jeroen T. Vermeulen <jtv@xs4all.nl>
 *
 * See COPYING for copyright license.  If you did not receive a file called
 * COPYING with this source code, please notify the distributor of this mistake,
 * or contact the author.
 *
 *-------------------------------------------------------------------------
 */

/* End-user programs need not include this file, unless they define their own
 * transaction classes.  This is not something the typical program should want
 * to do.
 *
 * However, reading this file is worthwhile because it defines the public
 * interface for the available transaction classes such as transaction and 
 * nontransaction.
 */

#include "pqxx/connection_base"
#include "pqxx/isolation"
#include "pqxx/result"

/* Methods tested in eg. self-test program test001 are marked with "//[t1]"
 */


namespace pqxx
{
class connection_base;
class transaction_base;


namespace internal
{
class PQXX_LIBEXPORT transactionfocus : public namedclass
{
public:
  transactionfocus(transaction_base &t, 
      const PGSTD::string &Name,
      const PGSTD::string &Classname) :
    namedclass(Name, Classname),
    m_Trans(t),
    m_registered(false)
  {
  }

protected:
  void register_me();
  void unregister_me() throw ();
  void reg_pending_error(const PGSTD::string &) throw ();
  bool registered() const throw () { return m_registered; }

  transaction_base &m_Trans;

private:
  bool m_registered;

  transactionfocus();
  transactionfocus(const transactionfocus &);
  transactionfocus &operator=(const transactionfocus &);
};
} // namespace internal




class PQXX_LIBEXPORT transaction_base : public internal::namedclass
{
  // TODO: Retry non-serializable transaction w/update only on broken_connection
public:
  typedef isolation_traits<read_committed> isolation_tag;

  virtual ~transaction_base() =0;                                       //[t1]


  void commit();                                                        //[t1]


  void abort();                                                         //[t10]


  result exec(const char Query[], 
              const PGSTD::string &Desc=PGSTD::string());               //[t1]


  result exec(const PGSTD::string &Query,
              const PGSTD::string &Desc=PGSTD::string())                //[t2]
        { return exec(Query.c_str(), Desc); }

  result exec(const PGSTD::stringstream &Query,
              const PGSTD::string &Desc=PGSTD::string())                //[t9]
        { return exec(Query.str(), Desc); }

  void process_notice(const char Msg[]) const                           //[t14]
        { m_Conn.process_notice(Msg); }
  void process_notice(const PGSTD::string &Msg) const                   //[t14]
        { m_Conn.process_notice(Msg); }

  connection_base &conn() const { return m_Conn; }                      //[t4]


  void set_variable(const PGSTD::string &Var, const PGSTD::string &Val);//[t61]


  PGSTD::string get_variable(const PGSTD::string &) const;              //[t61]

#ifdef PQXX_DEPRECATED_HEADERS

  void Commit() { commit(); }
  void Abort() { abort(); }
  result Exec(const char Q[], const PGSTD::string &D=PGSTD::string())
        { return exec(Q,D); }
  result Exec(const PGSTD::string &Q, const PGSTD::string &D=PGSTD::string())
        { return exec(Q,D); }
  void ProcessNotice(const char M[]) const { return process_notice(M); }
  void ProcessNotice(const PGSTD::string &M) const { return process_notice(M); }
  PGSTD::string Name() const { return name(); }
  connection_base &Conn() const { return conn(); }
  void SetVariable(const PGSTD::string &Var, const PGSTD::string &Val)
        { set_variable(Var,Val); }
#endif

protected:

  explicit transaction_base(connection_base &, 
                          const PGSTD::string &TName,
                          const PGSTD::string &CName);


  void Begin();

  void End() throw ();

  virtual void do_begin() =0;
  virtual result do_exec(const char Query[]) =0;
  virtual void do_commit() =0;
  virtual void do_abort() =0;

  // For use by implementing class:


  result DirectExec(const char C[], int Retries=0);
 
private:
  /* A transaction goes through the following stages in its lifecycle:
   * <ul>
   * <li> nascent: the transaction hasn't actually begun yet.  If our connection
   *    fails at this stage, it may recover and the transaction can attempt to
   *    establish itself again.
   * <li> active: the transaction has begun.  Since no commit command has been 
   *    issued, abortion is implicit if the connection fails now.
   * <li> aborted: an abort has been issued; the transaction is terminated and 
   *    its changes to the database rolled back.  It will accept no further 
   *    commands.
   * <li> committed: the transaction has completed successfully, meaning that a 
   *    commit has been issued.  No further commands are accepted.
   * <li> in_doubt: the connection was lost at the exact wrong time, and there
   *    is no way of telling whether the transaction was committed or aborted.
   * </ul>
   *
   * Checking and maintaining state machine logic is the responsibility of the 
   * base class (ie., this one).
   */
  enum Status 
  { 
    st_nascent, 
    st_active, 
    st_aborted, 
    st_committed,
    st_in_doubt
  };


  void CheckPendingError();

  friend class Cursor;
  friend class cursor_base;
  int GetUniqueCursorNum() { return m_UniqueCursorNum++; }
  void MakeEmpty(result &R) const { m_Conn.MakeEmpty(R); }

  friend class internal::transactionfocus;
  void RegisterFocus(internal::transactionfocus *);
  void UnregisterFocus(internal::transactionfocus *) throw ();
  void RegisterPendingError(const PGSTD::string &) throw ();
  friend class tablereader;
  void BeginCopyRead(const PGSTD::string &Table, const PGSTD::string &Columns);
  bool ReadCopyLine(PGSTD::string &L) { return m_Conn.ReadCopyLine(L); }
  friend class tablewriter;
  void BeginCopyWrite(const PGSTD::string &Table, 
        const PGSTD::string &Columns = PGSTD::string());
  void WriteCopyLine(const PGSTD::string &L) { m_Conn.WriteCopyLine(L); }
  void EndCopyWrite() { m_Conn.EndCopyWrite(); }

  friend class pipeline;
  void start_exec(const PGSTD::string &Q) { m_Conn.start_exec(Q); }
  internal::pq::PGresult *get_result() { return m_Conn.get_result(); }
  void consume_input() throw () { m_Conn.consume_input(); }
  bool is_busy() const throw () { return m_Conn.is_busy(); }

  connection_base &m_Conn;

  int m_UniqueCursorNum;
  internal::unique<internal::transactionfocus> m_Focus;
  Status m_Status;
  bool m_Registered;
  mutable PGSTD::map<PGSTD::string, PGSTD::string> m_Vars;
  PGSTD::string m_PendingError;

  transaction_base();
  transaction_base(const transaction_base &);
  transaction_base &operator=(const transaction_base &);
};

} // namespace pqxx

---