Some concepts that are needed to deploy apps with BOINC.
Apps and app versions
In BOINC, 'app' has a special meaning. It's the abstraction of a program: something that takes inputs and produces outputs. Each app has a unique name (like 'autodock').
An 'app version' is a specific executable file (or set of files) that performs this computation. It's associated with a particular app, and with a plaform (Windows/Intel, Mac/Intel, Linux/ARM, etc.).
App versions have version numbers (like 3.2). When the BOINC server sends a job to a client, it uses the app version for that platform with the largest version number.
The server cookbook shows how to create apps and app versions.
Plan classes
In some cases info beyond just platform is needed to decide whether an app version can run on a particular host. For example:
- The executable is compiled to use instructions (like SSE3) that exist on some Intel-compatible processors but not others.
- The program uses a GPU and requires a particular range of GPU models and video driver versions.
- The program requires that virtualization software (like VirtualBox) be installed on the host.
A set of such requirements is called a 'plan class'. An app version can be associated with a plan class, in which case it will be sent only to hosts that meet the requirements.
There are a number of pre-defined plan classes:
- mt: multithreaded programs that use from 2 to 16 cores.
- sse3: programs compiled to use SSE3 instructions.
- vbox_64: programs that use VirtualBox, 64-bit.
- cuda: programs that use NVIDIA GPU, compute capability 1.0+
You can define your own plan classes in XML. Details are here.
Files
File immutability
We're concerned here with files that are copied between client and server (input and output files, app version files). Such files are 'immutable'. All replicas of a file with a given name, from a given project, are assumed (and required) to be identical. If a file is change, even by a single byte, it becomes a new file and must be given a different name. This can be done, e.g., by including a version number in the file name.
Client directory structure
Input and output files have, in addition to their names (or 'physical names'), a 'logical name', which is the name by which the application refers to them. dir structure on client
The BOINC client, in its data directory, has two subdirectories:
- projects/ has a subdirectory for each project that the client is attached to.
- slots/ has a subdirectory for each currently active job.
The slot directory contains "link files", with logical names, that refer to the corresponding physical file in the project directory. Link files look like
<soft_link>../../projects/project.url.edu/phys_filename</soft_link>
Thus, the client directory structure looks like this:
In some cases (if indicated by a <copy/> tag the job or app version config file)
the client copies the file to the slot directory,
giving it the logical name.
Process structure
The BOINC client communicates with running jobs by message-passing through a shared memory segment. The client can tell the app to suspend or resume, or tell it to checkpoint. The app can reports its fraction done and CPU time to the client, or confirm that it's checkpointed.
The app side of this communication is done by a 'BOINC runtime library' - a C++ library that's linked into the application. The library also provides API functions for converting logical names to physical names (i.e. for parsing link files) and for initialization and finalization.
Every BOINC app must use the library. There are several ways to do this:
App packaging options
There are several ways to 'package' an application for use with BOINC:
- Native app: add BOINC API calls to the program source code, then compile it (for a given platform) and link it to the BOINC runtime library.
- Wrapper: use a BOINC-supplied program (wrapper) that interfaces between the BOINC client and an unmodified executable. This removes the need to change your program's source code, but you still need to build it for different platforms (e.g. Windows).
- VM apps: your app runs inside a virtual machine (typically Linux). A BOINC-supplied program called vboxwrapper interfaces between the BOINC client, VirtualBox, and the VM.
Each approach has pros and cons. The VM approach is most convenient - you don't have to build on Windows or Mac - but it has a performance overhead, and (currently) you can't use GPUs.