Difference between revisions of "FreeM System Architecture"

From FreeM Wiki
Jump to navigation Jump to search
 
Line 2: Line 2:
 
{{DevBranchFeature}}
 
{{DevBranchFeature}}
  
= Architecture =
+
= Overview =
  
[[media:FreeM Environment Diagram]]
+
[[File:FreeM Environment Diagram.png]]
 +
 
 +
= Namespaces =
 +
In FreeM, a [[Namespaces|namespace]] is a collection of [[Routines|routines]] and [[Globals|globals]]. Each environment must contain one and only one namespace called <code>SYSTEM</code>, and any number of other namespaces. Globals and routines whose name begins with the percent sign (<code>%</code>) must always be placed in the <code>SYSTEM</code> namespace.
 +
 
 +
In a given FreeM process, the <code>SYSTEM</code> namespace is always accessible, as well as one other active namespace, the latter of which is indicated in the direct-mode prompt.
 +
 
 +
= Environments =
 +
An ''environment'' is a collection of at least one ''namespace'', interpreter and <code>fmadm</code> processes, a set of after-image journals, and a daemon managing the lock and job tables, shared locals, and process housekeeping. FreeM (in the development branch) supports multiple environments per host system.
 +
 
 +
= Interpreter Processes =
 +
These are the processes running M code. They can be in ''direct mode'', meaning the process is taking input interactively from the terminal, ''application mode'', meaning the process's lifetime is tied to the lifetime of the M routine running within it, or ''library mode'', meaning the process is an instance of <code>libfreem</code>.
 +
 
 +
= fmadm Processes =
 +
The <code>fmadm</code> utility is used to manage FreeM environments, including loading and saving RSA/RO routine archives, backing up, restoring, and repairing globals, creating, modifying, and removing namespaces and environments, examining and potentially stopping current running processes, and placing environments into maintenance mode.
 +
 
 +
= After-Image Journals =
 +
After-image journals are files containing a record of logical operations performed on each global in the environment. They are used to provide consistency and durability in transaction processing, and recoverability from certain classes of system failure.
 +
 
 +
 
 +
= FreeM Daemon =
 +
The daemon, started once for each environment, manages resources shared by all processes in the environment. This includes the job table, lock table, and shared locals. The daemon also cleans up after crashed processes, and maintains the state of several structured system variables.
 +
 
 +
= Lock Table =
 +
The lock table manages advisory locking by tracking what processes own what locks, and how many processes have acquired said locks.
 +
 
 +
= Job Table =
 +
Manages process lifecycle, as well as process state for the <code>^$JOB</code> structured system variable.

Latest revision as of 19:35, 20 December 2024

This article's contents should eventually be integrated into the FreeM Manual as part of the official, bundled documentation.
This article documents one or more features currently implemented only in the development branch, and as such, may not apply to any current, official release.

Overview

FreeM Environment Diagram.png

Namespaces

In FreeM, a namespace is a collection of routines and globals. Each environment must contain one and only one namespace called SYSTEM, and any number of other namespaces. Globals and routines whose name begins with the percent sign (%) must always be placed in the SYSTEM namespace.

In a given FreeM process, the SYSTEM namespace is always accessible, as well as one other active namespace, the latter of which is indicated in the direct-mode prompt.

Environments

An environment is a collection of at least one namespace, interpreter and fmadm processes, a set of after-image journals, and a daemon managing the lock and job tables, shared locals, and process housekeeping. FreeM (in the development branch) supports multiple environments per host system.

Interpreter Processes

These are the processes running M code. They can be in direct mode, meaning the process is taking input interactively from the terminal, application mode, meaning the process's lifetime is tied to the lifetime of the M routine running within it, or library mode, meaning the process is an instance of libfreem.

fmadm Processes

The fmadm utility is used to manage FreeM environments, including loading and saving RSA/RO routine archives, backing up, restoring, and repairing globals, creating, modifying, and removing namespaces and environments, examining and potentially stopping current running processes, and placing environments into maintenance mode.

After-Image Journals

After-image journals are files containing a record of logical operations performed on each global in the environment. They are used to provide consistency and durability in transaction processing, and recoverability from certain classes of system failure.


FreeM Daemon

The daemon, started once for each environment, manages resources shared by all processes in the environment. This includes the job table, lock table, and shared locals. The daemon also cleans up after crashed processes, and maintains the state of several structured system variables.

Lock Table

The lock table manages advisory locking by tracking what processes own what locks, and how many processes have acquired said locks.

Job Table

Manages process lifecycle, as well as process state for the ^$JOB structured system variable.