Make behaviour of reference counting of games consistent.

The behaviour of reference counting of games has to date not been well-defined.
An object or variable holding a reference to an individual game element (player, outcome, etc.) was
not enough to extend the lifetime of a game object if the last
user-held reference to the game went out of scope (in either C++ or Python).
In contrast, a collection object (e.g. the set of players) did hold a shared reference to
the underlying game and therefore extended the lifetime of the game.

* Standardise on the semantics that holding a reference to any component
  element or elements of a game, or another indirect reference to
  a game via e.g. a profile, extends the lifespan of the underlying
  game.  (This is the same semantics as was used in the old
  Gambit Command Language.)
* Add a section in the `pygambit` user guide briefly explaining this.

Closes #537.

Author: tturocy

doc/pygambit.user.rst

@@ -334,6 +334,46 @@ Games stored in existing Gambit savefiles can be loaded using :meth:`.read_efg`
    cd ../../doc
 
 
+Lifetime of a game object and its elements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A game is only deallocated when all variables referring to the game either directly
+or indirectly have gone out of scope.  Indirect references to games include objects such
+as :py:class:`~pygambit.gambit.MixedStrategyProfile` or :py:class:`~pygambit.gambit.MixedBehaviorProfile`,
+or variables referring to individual elements of a game.
+
+So for example, the following sequence of operations is valid:
+
+.. ipython:: python
+   :suppress:
+
+   cd ../contrib/games
+
+
+.. ipython:: python
+
+   g = gbt.read_efg("e02.efg")
+   p = g.players[0]
+   print(p)
+   g = gbt.read_efg("poker.efg")
+   print(p)
+   print(g)
+
+.. ipython:: python
+   :suppress:
+
+   cd ../../doc
+
+The variable `p` refers to a player in the game read from ``e02.efg``.
+So, when ``poker.efg`` is read and assigned to the variable `g`, the game from
+``e02.efg`` is still referred to indirectly via `p`.  The game object from the
+first game can therefore still be obtained from the object referring to the
+player:
+
+.. ipython:: python
+
+   print(p.game)
+
 
 Computing Nash equilibria
 ~~~~~~~~~~~~~~~~~~~~~~~~~

src/games/game.h

@@ -175,6 +175,7 @@ class GameActionRep : public std::enable_shared_from_this<GameActionRep> {
   void Invalidate() { m_valid = false; }
 
   int GetNumber() const { return m_number; }
+  Game GetGame() const;
   GameInfoset GetInfoset() const;
 
   const std::string &GetLabel() const { return m_label; }
@@ -305,6 +306,8 @@ class GameStrategyRep : public std::enable_shared_from_this<GameStrategyRep> {
   /// Sets the text label associated with the strategy
   void SetLabel(const std::string &p_label) { m_label = p_label; }
 
+  /// Returns the game on which the strategy is defined
+  Game GetGame() const;
   /// Returns the player for whom this is a strategy
   GamePlayer GetPlayer() const;
   /// Returns the index of the strategy for its player
@@ -940,6 +943,9 @@ inline void GameOutcomeRep::SetPayoff(const GamePlayer &p_player, const Number &
 }
 
 inline GamePlayer GameStrategyRep::GetPlayer() const { return m_player->shared_from_this(); }
+inline Game GameStrategyRep::GetGame() const { return m_player->GetGame(); }
+
+inline Game GameActionRep::GetGame() const { return m_infoset->GetGame(); }
 
 inline Game GameInfosetRep::GetGame() const { return m_game->shared_from_this(); }
 inline GamePlayer GameInfosetRep::GetPlayer() const { return m_player->shared_from_this(); }

src/games/gameobject.h

@@ -27,6 +27,9 @@
 
 namespace Gambit {
 
+class GameRep;
+using Game = std::shared_ptr<GameRep>;
+
 /// An exception thrown when attempting to dereference an invalidated object
 class InvalidObjectException : public Exception {
 public:
@@ -35,18 +38,40 @@ class InvalidObjectException : public Exception {
   const char *what() const noexcept override { return "Dereferencing an invalidated object"; }
 };
 
+/// A handle object for referring to elements of a game
+///
+/// This class provides the facilities for safely referencing the objects representing
+/// elements of a game (players, outcomes, nodes, and so on).
+///
+/// This addresses two issues:
+///   * Holding a reference to some element of a game counts as holding a reference to the
+///     whole game.  This encapsulates such reference counting such that a game is only
+///     deallocated when all references to any part of it are deallocated.
+///   * Because games are mutable, the element of the game referred to by this class
+///     may be removed from the game.  When an element is removed from the game, it is
+///     marked as no longer valid.  This class automates the checking of validity when
+///     dereferencing the object, and raising an exception when appropriate.
 template <class T> class GameObjectPtr {
   std::shared_ptr<T> m_rep;
+  Game m_game;
 
 public:
   GameObjectPtr() = default;
-  GameObjectPtr(std::nullptr_t r) : m_rep(r) {}
-  GameObjectPtr(std::shared_ptr<T> r) : m_rep(r) {}
+  GameObjectPtr(std::nullptr_t r) : m_rep(r), m_game(nullptr) {}
+  GameObjectPtr(std::shared_ptr<T> r) : m_rep(r), m_game((r) ? r->GetGame() : nullptr) {}
   GameObjectPtr(const GameObjectPtr<T> &) = default;
   ~GameObjectPtr() = default;
 
   GameObjectPtr<T> &operator=(const GameObjectPtr<T> &) = default;
 
+  /// Access the shared pointer to the object representing the game element
+  ///
+  /// Returns the shared pointer to the game element.  Checks for the validity of the
+  /// game element held by this object and throws an exception if the object is the
+  /// null object, or is no longer valid (has been removed from the game)
+  ///
+  /// @exception NullException if the object holds a reference to a null element
+  /// @exception InvalidObjectException if the element referred to has been deleted from its game
   std::shared_ptr<T> operator->() const
   {
     if (!m_rep) {
@@ -57,6 +82,15 @@ template <class T> class GameObjectPtr {
     }
     return m_rep;
   }
+
+  /// Access the shared pointer to the object representing the game element
+  ///
+  /// Returns the shared pointer to the game element.  Checks for the validity of the
+  /// game element held by this object and throws an exception if the object is the
+  /// null object, or is no longer valid (has been removed from the game)
+  ///
+  /// @exception NullException if the object holds a reference to a null element
+  /// @exception InvalidObjectException if the element referred to has been deleted from its game
   std::shared_ptr<T> get_shared() const
   {
     if (!m_rep) {
@@ -67,6 +101,15 @@ template <class T> class GameObjectPtr {
     }
     return m_rep;
   }
+
+  /// Access the raw pointer to the object representing the game element
+  ///
+  /// Returns the raw pointer to the game element.  Checks for the validity of the
+  /// game element held by this object and throws an exception if the object is the
+  /// null object, or is no longer valid (has been removed from the game)
+  ///
+  /// @exception NullException if the object holds a reference to a null element
+  /// @exception InvalidObjectException if the element referred to has been deleted from its game
   T *get() const
   {
     if (!m_rep) {