GMT Modern Mode: Under the Hood

This pages discusses how modern mode has been implemented given the fact that classic mode is the default GMT run mode.

1. The unique session ID

The GMT modern mode relies on having a unique ID number that can be obtained by the gmt application when it starts. We are relying on the standard UNIX library for this, in particular

  1. getppid, which returns the process ID of the parent process
  2. getpid, which returns the current process ID.

For command-line usage in a UNIX shell we use method (1). Hence interactive sessions or individual scripts will have a constant ID seen by all the modules. This means you can run any number of scripts from separate terminal windows. For external usage via the C API we instead use method (2) to get the process ID of the application that is calling the API. So far, there are a few situation where this approach fails:

  1. Using Windows executables GMT from Unix clone-shells, such as Cygwin and MSYS. Here, getppid (i.e., a Windows reimplementation since the UNIX library function does not exist) returns different PPIDs despite being launched in the same shell.
  2. During cmake testing, the test script commands that involve piping are executed in what appears as subshells and these have their own PPID.

We deal with these problems in different ways. For the time being, if we find we are in situation (1) then we are enforcing a PPID = 0. The downside to this scheme is that users cannot run several scripts concurrently. The alternative is to set an environmental parameter in the script called GMT_PPID. If set, then gmt will use this value instead. For the cmake testing we simply add export GMT_PPID=$$ to have all modules in the same script detect the same process number of the parent script.

2. The unique temporary work directory

Given the PPID we create a temporary directory called /tmp/gmt6.<PPID> where all temporary files are placed. These are control files used to manage the modern session and they are all deleted, as is the directory, when the modern session end with gmt end. Clearly, if different GMT sessions could not have unique PPIDs then this would not work, hence the concerns above.

3. The modern session management files

When a new session is initialized by gmt begin, the temporary directory is created and then a few files are written to it (and one will be created once the session starts in earnest). These are

  1. gmt.conf – The current settings that differ from the GMT defaults.
  2. gmt.history – The history of common option settings during this session

Additional management files are created using the gmt subplot and gmt figure commands. If gmt figure is used to define a new figure, its name and format we will add the file

  1. gmt.figures — The list of all registered figures so far.
  2. gmt.current — The name and number of the current plot.
  3. gmt_<ID>.ps- — The file holding this figure's PostScript output so far.
  4. gmt_<ID>.layers — The file holding the byte count to the end of each PostScript layer for this figure. This is used by gmt revert to strip off layers.

GMT allows you to switch between different figures so if you run gmt figure and give an already registered figure then we simply make that (already existing) figure the current figure (and thus only update the gmt.current file).

Using gmt subplot to set up a multi-panel (subplot) figure will also create management files:

  1. gmt_<ID>.subplot — Information about each panel in the subplot
  2. gmt_<ID>.panel — Information about which panel is the current active panel

Here, <ID> stands for the current active figure ID. These files are deleted when gmt subplot end is called.

4. The removal of the session

The above management files will live until the end of the session, which ends when gmt end is called. At that point, any finalization of figures (e.g., conversion to the chosen graphic formats) will take place and the results are placed in the current working directory. The temporary work directory and its contents are then removed.