SPY HILL Research Spy-Hill.com

Poughkeepsie, New York [DIR] [UP]

The 'scroll' application for Pirates@Home

The 'scroll' appllication for BOINC show text scrolling up the screen and off into the distance, as in the openings of the Star Wars movies. The input file can be obtained from one of several possible sources on the Internet, such as the archive of classic novels from Project Guttenberg.

This is not a good example to emulate. See instead the cube and lalanne examples.

Last modified: 3 October 2009
Getting the code
Release Notes
The "scroll" application for BOINC reads a data file and displays the contents of the file line by line on the screensaver or graphics window, scrolling out into the distance of an approaching starfield, much like the opening of the Star Wars movies.

One purpose of this application, aside from the fun of showing the scrolling text, was to test BOINC's capabililies for obtaining data files from a distributed set of servers. When this is working, the text displayed will be obtained from one of the Project Guttenberg mirror sites, not the Pirates@Home site.

The way that this application is structured is actually a bit pathelogical. The computation thread (which reads in the data) depends upon the graphics thread (which displays the data), and it is possible for the two to get way out of sync. You would do well to not emulate this structure, and in fact you would do well to not use this application as an example for anything but what to avoid.


The original scroll was rushed into service, and so it only had the bare bones of a BOINC application. I didn't have time to work on scroll until after exams were ended at Vassar and holiday preparations at home were taken care of. Then I got the idea to send out a holiday greeting to the crew. My wife suggested the poem "'Twas the Night Before Christmas" (or "A visit from St. Nicholas") because it was in fact Christmas eve. I liked the idea for that reason, and because my Vassar colleague Donald Foster was the one who had suggested that Henry Livingston, Jr. was the true author rather than Clement Clarke Moore. I also liked it because the poem would fit in under 100 lines of text, which was all the program could handle. Future versions of scroll were able to deal properly with much longer texts.

The original version of scroll had no checkpointing. That meant that if the task was interupted (stopped, not just paused) then it would restart from the beginning. This was fine for a short display, but not for longer texts.

The original version of scroll did not set the progress information correctly. Even if the job was making progress, it just registered "47%" for the whole time in the BOINC control panel. I picked 47% because I am a graduate of Pomona College (google for "Pomona 47" for the full story). This wasn't a bug, it was just that I didn't have time to add the progress reporting.

What is most strange about scroll is that completion is signaled by the graphics thread, when the text had scrolled out to the end, rather than by the computation thread. This is backwards from most BOINC applications. This had the unintended consequence that if a user was not displaying graphics (either with the show graphics window or as a screensaver) then the task would just burn up all of the allotted time and then exit with an error code.

The first version of scroll (version 4.52), didn't even write an output file. That caused an error when the workunit was finished, even if the graphics thread was run. So version 4.52 was never released to the crew.

Version 4.53 wrote a simple output file and ran succesfully to completion on my test machine, so it was released to the crew on Christmas eve, with work generated fairly quickly and steadily to get the greeting out.

When problems were reported I added proper reporting of progress for the BOINC control panel (now called the Manager), and also wrote the progress to the screen (for at least two versions). Versions 4.54 to 4.56 were variations on this, though they still only set the progress in the graphics thread. Workunits run by clients not displaying graphics would still end with an out-of-time error.

At the time this was happening it was hoped that this behaviour might shed some light on errors that had been observed with Workunits on other BOINC projects running to completion but then requesting zero credit even though no error was reported. The two problems turned out to be unrelated, but it was worth trying to see if they had something in common.

While I was working on the changes leading to version 4.56 I also edited the message file, which was called NightBeforeXmas.txt. But I did not change the name of the file, and that is a big no-no for BOINC. Files in BOINC are supposed to be unique by name, and the file size and an MD5 hash are used to verify that the file has not been altered or garbled in transport. Users who had already received the original version of the file had the original size and MD5 hash on record, and then when the new version was downloaded it did not match, which registered as a download error. BOINC may have kept trying to download this file because it thought that the error was in transport, not a change on the server.

I goofed on this, but it was a useful demonstration that BOINC does what it is supposed to do. If a file does not match the size or MD5 hash then it is considered to be incorrect. This is used to verify that all data files are downloaded correctly from the server, and it clearly works.

For version 4.57 I changed the data file name to NightBeforeXmas2.txt and I added a timeout for workunits that ran without starting the graphics thread. The progress readout is correct for those workunits even if the graphics thread never starts. In future versions the timeout may be shorter, but non-graphical users should still get credit for succesful completion of a workunit.

Instead of generating new work, I simply updated to version 4.57 on the project and let older failed workunits go out to new clients with the updated software. The success rate for 4.57 went up to about 92% the day after Christmas, with about 300 Results still "in progress".

Later versions of scroll added checkpointing, and user input from the keyboard to speed up or slow the text or alter the view.

This strange application demonstrated that a large number of users were running applications on Pirates@Home without viewing the graphics. That is fine, and I'll try to make sure that they work that way, but for the past few months Pirates has only been testing graphics, so there isn't much point in worrying about results run without graphics.

Getting the code

You can get a tarball containing the source code and build scripts here.

On unix you can use CVS to get the code thus:

$  cvs -d :pserver:anonymous@spy-hill.net/usr/local/cvsroot/boinc checkout src/apps/scroll.d
Then move the directory scroll.d to wherever you want to use it. On Windows you need to put this in the boinc/apps folder.

Release Notes

Here are more specific notes for particular versions of scroll as they were released. (This list is incomplete and needs to be reconstructed from the notes in the discussion forums.)
scroll 5.02   (17 September 2006)
Not starting graphics within 15 minutes ends in an error. Less work per iteration of main loop, and possibly multiple lines read into the buffer, to help slower machines.
scroll 5.01   (16 September 2006)
Updated for BOINC version 5 in time for International Talk Like a Pirate Day. Added keyboard functions for Unix.

scroll 4.66-67  (10 January 2005)
Treasure Island
scroll 4.63  (5 January 2005)
Checkpointing restarts correctly, or starts correctly at the line given in the params file if it exits.
scroll 4.62  
Checkpoint works but viewpoint doesn't catch up read params file to start at a given line number rather than the first line of the file.
scroll 4.61  
Can read a file with arbitrary number of lines. Text literallly fades into the distance
scroll 4.60  
Set all_done true when non-graphics timeout. Why wasn't this done earlier?
scroll 4.59  
When worker thread restarted it did not restart the line count, so it seemed as if the count was longer than the file. Fixed.
scroll 4.58  (1 January 2005)
Built with BOINC core 4.57 (doing that was non-trivial: Added graphics_impl.C/h and mem_usage.C/h, modified boinc_win.h to put back afx includes modified gutil.C to not extern "C" the #include "jpeglib.h"
Changed input file to AuldLangSyne1.txt
Keyboard input: ctrl-> speeds up, ctrl -< slows down ctrl S toggles stars, ctrl B toggles "banner" Stroke fonts used for some screen annotations. User info added to screen. GMT time displayed (or not: ctrl-T). Application name and version displayed. Workunit name displayed. Speed and position displayed (ctrl or shift keys held).
scroll 4.57   (26 December 2004)
Added timeout to computation thread, so will not fail with error even if graphics don't run Changed file to NightBeforeXmas2.txt
scroll 4.56  (25 December 2004)
Added progress settings in graphics thread.
scroll 4.54-55
various small changes
scroll 4.53  (25 December 2004)
Created a small output file to fix completion.
scroll 4.52   (24 December 2004)
Original version submitted to the Pirates@Home crew, with the following:
  • no checkpointing. Starts over if interupted.
  • no progress information: set at 47% always
  • no completion unless graphics runs to end
  • no output file -- so error at the end

Last modified: Saturday October 03, 2009 Copyright © 2009 by Spy Hill Research http://www.spy-hill.com /~myers/help/boinc/scroll.html