The BOINC core/application interface, version 4.0

BOINC logo

This document proposes:

Required functionality

The core/app interface consists of static and dynamic parts. The static part consists of files that are written to the app's 'slot' directory prior to running the app, such as the 'app_init_data.xml' file. We don't propose any changes to this part.

The dynamic part must support several functions:

The version 3 interface and its shortcomings

The version 3 interface uses shared-memory message-passing for CPU time reporting, heartbeat, trickle messages and graphics. It uses signals (Unix) and SuspendThread-type calls (Windows) for suspend/resume/quit. It uses a disk file for reliable finishing.

This interface has several shortcomings:

The version 4 interface

The version 4 interface is similar to version 3 except that it uses shared-memory message-passing for suspend/resume/quit, and it separates some message channels.

Version 4 uses the following message channels:

process_control_req (core->app) <suspend/>, <resume/>, <quit/>
process_control_reply (app->core) same as above
graphics_req (core->app) <window/>, <fullscreen/>, <none/>
graphics_reply (app->core) same as above
heartbeat (core->app) <heartbeat/>, <ignore_heartbeat/>
status (app->core) <fraction_done>, etc.
trickle_up (app->core) <have_new_trickle_up/>
trickle_down (core->app) <have_new_trickle_down/>

The BOINC API: single-process applications

The BOINC API is revised as follows:
	boinc_init(int flags)
This creates a 'manager thread'; the calling thread is the 'worker thread'. The 'flags' argument specifies which message streams will be handled by the manager thread. By default, it handles the following message streams:

process_control_req The manager thread suspends and resumes the worker thread. It uses a semaphore to avoid suspending or aborting the worker thread while it's checkpointing.
heartbeat It does exit(ERR_NO_HEARTBEAT) if heartbeat is lost
status It measures and reports worker thread CPU time
trickle_up
trickle_down

	boinc_init_graphics()
is unchanged; it creates a 'graphics thread' that calls application-supplied functions to render graphics and handle input.
	boinc_finish()
is unchanged: it creates a 'finish file' and exits.

The BOINC API: compound applications

Compound applications consist of a 'controller' program that runs one or more 'worker' programs in sequence. Graphics may be provided by the work programs, or by a separate graphics program that is run by the controller.

Version 4.0 leaves it up to the developer to decide which message channels are handled by which program. For example, suspend/resume messages might be handled by either the controller or the worker.

The following lower-level API functions are provided:

boinc_parse_app_init_data()
boinc_attach_shmem()
boinc_get_message
Here's an example in which the controller program handles graphics messages, and the work programs handle suspend/resume:
Controller program:
	boinc_parse_app_init_data()
	boinc_attach_shmem()
	while (1)
		boinc_write_app_init_data()
		spawn next worker program
		while (1)
			if worker has finished
				if successful
					break
				else
					exit
			if have graphics message
				start or kill graphics program
		boinc_parse_app_init_data()
	boinc_finish()

Worker program:
	boinc_init()
	...
	write 'phase done' file
	exit(0)		// don't call boinc_finish()

Return to BOINC main page

Last modified 8:51 PM UTC, October 17 2012.
Copyright © 2017 University of California. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation.