Sessions Guide

FracTest internally stores information in several files, for various purposes, such as settings, history, and checkpointing. These files are organised into sessions, to allow multiple app instances to run concurrently.

This section describes the operation of sessions in FracTest.

Overview

FracTest stores information internally in files for multiple purposes:

the settings;
the user's browsing history; and
computation checkpoints.

Having multiple application windows running at once, and all writing to the same files, would be a problem; different app instances would overwrite each others' checkpoints, for example, and would alter each others' histories.

To prevent this, FracTest organises these files into sessions. A session can only be opened in one application instance at a time; however, multiple copies of FracTest can be running simultaneously, in different sessions.

When you start FracTest, you will generally need to choose a session to run in (unless there is only one). From FracTest, you can always open a different session; and sessions can be created, renamed, and deleted.

File Storage

All of FracTest's internal files are stored in the user's default files directory. Where this is depends on your operating system:

On Windows, this should be in the user's My Documents directory, in a sub-folder called FracTest.
On MacOS, this should be in the user's home/Documents directory, in a sub-folder called FracTest.
On Unix-like systems (including Linux), this should be in the user's home directory, in a sub-folder called .FracTest (note this name begins with a dot, and is a hidden folder).

Within the FracTest folder, there is a sub-folder called Sessions; within this there is a sub-folder for each session, named by the session's name.

Each session's folder contains a file named settings, if the user has configured any settings for that session; note that there is no filename suffix.

The session's folder also contains several sub-folders, one for each FracTest function which keeps files. Currently, the sub-folders are history and checkpoint, for the respective functions.

Session Locking

A session may only be opened by one FracTest instance at a time. To enforce this, a lock file, named SessionLock (again with no filename suffix) is created in the session folder. This is created when the session is opened, and automatically deleted when it is closed.

In the event of a non-standard shutdown, such as a computer crash, this lock file may be left in place inappropriately; in this case, the session will appear to be locked when in fact it is not in use. The application provides a facility, described below, to forcibly unlock the session in this case.

Usage

When FracTest starts normally, it will check to see what sessions exist:

if there are none, it will create a session called Default, lock it, and start operating in it.
if there is exactly one, it will attempt to lock it, and start operating in it; if the session is already locked, it will pop up the session chooser.
if there is more than one, it will pop up the session chooser.

The effect of this is that if you never create any sessions, you will have just one, called Default, which will always be automatically selected without resorting to the session chooser. If you want to create another session, use the menu command "File" → "Open Session...", as described below.

The Session Chooser

The session chooser presents the user with a list of available sessions, controls to manage them, and controls to open a session. A typical example is shown at right (click to expand).

The session management controls are fairly self-explanatory:

New...: Prompts the user for a session name, and creates a session with that name. It is an error if the session already exists.
Rename: You must first select a session by clicking it. FracTest then prompts for a new name, and renames the selected session to that name. It is an error if the new name already exists. The session must not be in use.
Delete: You must first select a session by clicking it. FracTest then prompts for confirmation, and deletes the selected session. This deletes all settings, history, and checkpoints in the selected session. The session must not be in use.

Valid session names consist of letters and digits, spaces, and the underscore and + symbol. Any name containing other characters is disallowed.

To open a session, select it and click OK; or you can just double-click its name.

Unlocking

Any session which is seen as locked is flagged as locked in the session list.

As mentioned earlier, a crash can leave a session locked when it is not actually in use. To get around this, you can click the locked indicator to forcibly unlock a session. This feature must be used with care: if you accidentally unlock a session which is actually in use, bad things may happen to checkpoints and the history.

FracTest will attempt to perform some safety checks, and then prompt for confirmation; it will then delete the lock file.

Usage in FracTest

Once FracTest is running, the current session name is shown in a box just below the toolbar:

The Toolbar, Session Name ("Explore"), and Image Title (click to expand).

To change sessions, or to manage your sessions, use the menu command "File" → "Open Session...". This pops up the session chooser described above, which allows you to create, rename, and delte sessions.

You can also choose a session to open. In this case, a new FracTest window will open, running in the selected session. The existing window remains open. As described earlier, you can't open a session which is already open.

Batch Mode

Since batch mode is designed to operate without user interaction, the session chooser will never appear. Instead, you can select which session the batch application will run in using the --session command-line argmuent. If you do not specify a session, then FracTest will attempt to run in a session named Batch.

If the chosen session doesn't exist, it will be created; then it will be locked and used as normal. If it can't be locked — for example, if it's already in use — the an error will be displayed and FracTest will exit.

Hence, if you want to have multiple batch modes running at once, you will need to set the session name on the command line.