The BOINC core/application interface, version 4.0

---

This document proposes:

• revisions to the interface between the BOINC core client and applications.
• corresponding changes to the BOINC API and its implementation.

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:

• CPU time reporting: the app tells the core its CPU time and fraction done
• Heartbeat (if the core dies unexpectedly, the app should quit)
• Suspend/resume/quit (commands issued by the core)
• Reliable finishing (the core should regard an app as 'done' only if it's really done)
• Graphics (commands issued by the app to start/stop graphics)
• Reporting of trickle messages from and to the app

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:

• Suspend/resume doesn't work for compound applications. The controller, rather than the worker, is affected.
• Suspend/resume/quit is not synchronized with checkpointing.
• Single message-passing channels are used for multiple purposes, which limits the implementation options on the app side.

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 1:02 AM UTC, March 03 2019.
Copyright © 2025 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.