15.1 Theory of Operation

FreeM uses a pessimistic concurrency control mechanism for SERIAL transactions, meaning that any TSTART command that includes the SERIAL transaction parameter will cause the process to acquire the transaction processing mutex, which prevents any process but the one holding the mutex from performing any database access (read or write) until either TCOMMIT or TROLLBACK is called, either committing or rolling back the transaction, respectively.

Any transaction in between its TSTART and TCOMMIT/TROLLBACK is said to be in-flight. During the in-flight stage, pending database operations are held only in memory and after-image journals.

FreeM maintains a list of all globals affected during a transaction in-flight. When a TCOMMIT is reached, FreeM will generate a checkpoint of each global database file to be changed by the transaction. These checkpoints allow all FreeM globals to be restored to their pre-transaction state if a TCOMMIT should fail part of the way through its operation.

Checkpoints can have one of two modes:

CP_REMOVE

Used for globals that did not exist prior to the beginning of this transaction. Simply marks the entire global database file for deletion in case of TCOMMIT failure.

CP_RESTORE

Used for globals that did exist prior to the beginning of this transaction. In this case, the entire global database file is copied to a new file with a .chk extension. In cases of TCOMMIT failure, CP_RESTORE checkpoint files will be restored over the partially-modified live database file.

The below example shows a few database operations and checkpoints for a transaction in-flight using the trantab direct-mode command:

TL1:USER> trantab
 $TLEVEL 1*
  Operations for Transaction ID: 6ea14aad-b8f1-47f9-9f52-4f513f892bc0 [RESTARTABLE SERIAL]

   OP. NO.   ACTION         KEY/DATA
   -------   ------         --------
   1         SET            ^FOO=3
   2         KILL           ^FOO
   3         SET            ^jpw=10
   4         SET            ^BRANDNEW=6

  Global database checkpoints:

   GLOBAL                        MODE                FILES
   ------                        ----                -----
   ^BRANDNEW                     CP_REMOVE           IN:   /usr/local/var/freem/USER/globals/^BRANDNEW
   ^jpw                          CP_RESTORE          IN:   /usr/local/var/freem/USER/globals/^jpw
                                                     OUT:  /usr/local/var/freem/USER/globals/^jpw.23390.1.chk
   ^FOO                          CP_RESTORE          IN:   /usr/local/var/freem/USER/globals/^FOO
                                                     OUT:  /usr/local/var/freem/USER/globals/^FOO.23390.1.chk

In the above example, IN files are the live database file that will be overwritten or removed, and OUT files are the checkpoints themselves. Note that OUT files are only used for CP_RESTORE checkpoints.

This document was generated on September 20, 2023 using texi2html 5.0.