tsh GUI Notes

Development notes on the experimental GUI.

Updated Fri Sep 14 09:13:49 EDT 2007 for tsh 3.200.

An experimental version of the tsh GUI first shipped with version 3.190. This file documents the GUI, and will be entitled Notes to remind the reader of the experimental status of the module until it is ready for formal release.

Overview

The tsh graphical user interface (GUI) is implemented by having tsh run a lightweight web server on a nonstandard port. If the host machine supports it, the classic command-line interface (CLI) may be run simultaneously with the GUI.

Requirements

The experimental code is tested regularly under OS/X 10.4 and Windows XP. It is not guaranteed to work at all under other operating systems.

Earlier versions of Perl 5.8 did not return the correct value from threads::shared::share(). 5.8.6 works, 5.8.0 does not. Always use the latest greatest version of Perl. (Of course, versions of Perl prior to 5.8 did not support the current threads library at all, and don’t have a hope of running the threaded code.)

Configuration

To enable the GUI, add the line “config port = 7777” to your event’s ‘config.tsh’ file, where the value 7777 may be changed to any convenient value between 1024 and 65535.

To enable multithreaded operation, that is, simultaneous operation of the CLI and GUI, create a file called ‘threads.txt’ in the ‘lib’ directory. Yes, I know this is a hack, but it’s set up this way because enabling threading induces potential instability in the software (because of ridiculous restrictions on thread-shared data in the current release of the Perl threads library, which itself is not a mature product). I want to make sure that a user does not accidentally turn on multithreading until I’m 100% sure that the code won’t is sound. Another problem is that the way the code is written right now, and the way threads work in the current version of Perl, the obvious solution (a line in ‘config.tsh’) doesn’ work because by the time the configuration file is being read, it’s too late to activate multithreading (because the configuration file data itself would need to have been labelled as thread-shared).

If you’re successful, then when you run tsh, your CLI should appear briefly, then be superseded by a browser window showing something like a wall chart. If you’re running multithreaded, you can work alternately in the CLI and GUI windows.

Using the GUI

It’s just a proof-of-concept right now, and I don’t like the way any of it looks or functions. I’ll be reworking it over the next few months, at which point suggestions will be welcome.

Reconnecting to the GUI

If you close your browser window, you can reconnect to the GUI either by remembering the URL – ‘http://localhost:7777’ (if you chose 7777 as your port number), or looking for the URL in your browser history. If you have the CLI running too, you may use the “GUI” command to open a browser window to the GUI.

Shutting down the GUI

If you have the CLI running, quitting the CLI should shut down the GUI. Actually, there's a bug in the current version that prevents it from doing so under Windows, so press Control-C to kill the tsh process.

If not, you'll just have to press Control-C for now. Eventually there will be a button in the GUI to shut down the server.