SPY
HILL
Research
Poughkeepsie, New York
SPY
HILL
Research
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 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.
Topics History Getting the code Release Notes 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.
History
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.dThen move the directory scroll.d to wherever you want to use it. On Windows you need to put this in the boinc/apps folder.
Copyright © 2009 by Spy Hill Research http://www.Spy-Hill.net/help/boinc/scroll.html (served by Islay.spy-hill.com) Last modified: 03 October 2009