Line data    Source code

       1              : // SPDX-FileCopyrightText: 2017 Anne Jan Brouwer
       2              : // SPDX-License-Identifier: GPL-3.0-or-later
       3              : /**
       4              :  * @file
       5              :  * @brief SimpleTransaction, the bookkeeping that lets ImitatePass report
       6              :  * several queued processes as one finished operation.
       7              :  */
       8              : #ifndef SRC_SIMPLETRANSACTION_H_
       9              : #define SRC_SIMPLETRANSACTION_H_
      10              : 
      11              : #include "enums.h"
      12              : #include <queue>
      13              : 
      14              : /**
      15              :  * @class SimpleTransaction
      16              :  * @ingroup backend
      17              :  * @brief Tracks a sequence of processes that should be treated as one atomic
      18              :  * operation.
      19              :  *
      20              :  * ImitatePass queues several processes for one operation (gpg, then
      21              :  * `git add`, then `git commit` for an insert) and wants to report the
      22              :  * operation once, when the last of them ends. Between transactionStart()
      23              :  * and transactionEnd() it calls transactionAdd() for each process it
      24              :  * queues; transactionEnd() names the result to report. As processes finish,
      25              :  * transactionIsOver() answers with that result for the last one of a
      26              :  * transaction and with Enums::INVALID for every earlier one. Transactions
      27              :  * may nest; only the outermost one counts.
      28              :  */
      29          190 : class SimpleTransaction {
      30              :   /** @brief How many transactionStart() calls are still open. */
      31              :   int transactionDepth{0};
      32              :   /**
      33              :    * @brief The process most recently added to the open transaction, or
      34              :    * Enums::INVALID when none was added yet.
      35              :    */
      36              :   Enums::PROCESS lastInTransaction{Enums::INVALID};
      37              :   /**
      38              :    * @brief Closed transactions awaiting completion, oldest first: the
      39              :    * process that ends each one, and the result to report when it does.
      40              :    */
      41              :   std::queue<std::pair<Enums::PROCESS, Enums::PROCESS>> transactionQueue;
      42              : 
      43              : public:
      44              :   /**
      45              :    * @brief Construct a SimpleTransaction in its initial idle state.
      46              :    */
      47          190 :   SimpleTransaction() {}
      48              :   /**
      49              :    * @brief Open a transaction: the processes added until the matching
      50              :    * transactionEnd() are reported as one operation.
      51              :    */
      52              :   void transactionStart();
      53              :   /**
      54              :    * @brief Note that @p process has been queued.
      55              :    *
      56              :    * Inside an open transaction it becomes the transaction's latest step.
      57              :    * Outside one it is a transaction of its own, reported as itself.
      58              :    * @param process The process just queued.
      59              :    */
      60              :   void transactionAdd(Enums::PROCESS process);
      61              :   /**
      62              :    * @brief Close the transaction opened by the matching transactionStart().
      63              :    *
      64              :    * When the outermost transaction closes and at least one process was
      65              :    * added, the last one added becomes the step that completes it.
      66              :    * @param process What transactionIsOver() reports once that step ends.
      67              :    */
      68              :   void transactionEnd(Enums::PROCESS process);
      69              :   /**
      70              :    * @brief Tell whether the process that just finished ends the oldest
      71              :    * pending transaction, and take that transaction off the queue if so.
      72              :    * @param current The process that just finished.
      73              :    * @return The transaction's result as set by transactionAdd() or
      74              :    *         transactionEnd(), or Enums::INVALID while the transaction has
      75              :    *         steps left.
      76              :    */
      77              :   auto transactionIsOver(Enums::PROCESS current) -> Enums::PROCESS;
      78              : };
      79              : 
      80              : #endif // SRC_SIMPLETRANSACTION_H_