Options and status APIs

Setting options

You can customize the behavior of the BOINC runtime system by using boinc_init_options() instead of boinc_init():

BOINC_OPTIONS options;

boinc_options_defaults(options);
options.multi_thread = true;    // include this if your app's main process uses multiple threads
options.multi_process = true;   // include this if your app uses multiple processes

boinc_init_options(&options);

Do not create any threads or store the current PID before calling boinc_init_options(). The following options are available:

struct BOINC_OPTIONS {
    int normal_thread_priority;
    int main_program;
    int check_heartbeat;
    int handle_trickle_ups;
    int handle_trickle_downs;
    int handle_process_control;
    int handle send_status_msgs;
    int direct_process_action;
    int multi_thread;
    int multi_process;
};

The options are:

normal_thread_priority

If set, the application will run at normal thread priority (Windows). This is recommended for CUDA applications, so that the GPU will run at full speed even if the CPUs are loaded. Default is false.

The remaining options determine what runtime system functions will be performed by this program. This is primarily for the use of compound applications. In developing a compound application you must decide whether these functions are to be performed by the main or worker program. Each flag must be set in either the main or worker programs, but not both.

main_program

Set this in the main program.

check_heartbeat

If set, the program monitors 'heartbeat' messages from the core client. If the heartbeat stops, the result depends on the direct_process_action flag (see below).

handle_trickle_ups

If set, the program can send trickle-up messages.

handle_trickle_downs

If set, the program can receive trickle-down messages.

handle_process_control

If set, the program will handle 'suspend', 'resume', and 'quit' messages from the core client. The action depends on the direct_process_action flag.

send_status_msgs

If set, the program will report its CPU time and fraction done to the core client. Set in worker programs.

direct_process_action

If set, the program will respond to quit messages and heartbeat failures by exiting, and will respond to suspend and resume messages by suspending and resuming. Otherwise, these events will result in changes to the BOINC_STATUS structure, which can be polled using boinc_get_status().

multi_thread

Set this if your application uses multiple threads (e.g., OpenMP or pthreads).

multi_process

Set this if your application crease sub-processes (e.g., MPI).

Miscellaneous data

The following functions return miscellaneous data:

int boinc_get_init_data_p(APP_INIT_DATA*);
int boinc_get_init_data(APP_INIT_DATA&);

struct APP_INIT_DATA {
    int major_version;
    int minor_version;
    int release;
    int app_version;
    char app_name[256];
    char symstore[256];
    char acct_mgr_url[256];
    char* project_preferences;
    int hostid;
    char user_name[256];
    char team_name[256];
    char project_dir[256];
    char boinc_dir[256];
    char wu_name[256];
    char authenticator[256];
    int slot;
    double user_total_credit;
    double user_expavg_credit;
    double host_total_credit;
    double host_expavg_credit;
    double resource_share_fraction;
    HOST_INFO host_info;
    PROXY_INFO proxy_info;  // in case app wants to use network
    GLOBAL_PREFS global_prefs;
    double starting_elapsed_time;

    // info about the WU
    double rsc_fpops_est;
    double rsc_fpops_bound;
    double rsc_memory_bound;
    double rsc_disk_bound;

    // the following are used for compound apps,
    // where each stage of the computation is a fixed
    // fraction of the total.
    double fraction_done_start;
    double fraction_done_end;
};

to get the following information:

core version	The version number of the core client
app_name	The application name (from the server's DB)
project_preferences	An XML string containing the user's project-specific preferences.
user_name	The user's 'screen name' on this project.
team_name	The user's team name, if any.
project_dir	Absolute path of project directory
boinc_dir	Absolute path of BOINC root directory
wu_name	Name of workunit being processed
authenticator	User's authenticator for this project
slot	The number of the app's 'slot'
user_total_credit	User's total work for this project.
user_expavg_credit	User's recent average work per day.
team_total_credit	Team's total work for this project.
team_expavg_credit	Team's recent average work per day.
host_info	A structure describing the host hardware and OS
starting_elapsed_time	Elapsed time, counting previous episodes (provided only by 6.10 and later clients)

Getting the status of the runtime system

The status of the runtime system is represented by the following structure:

typedef struct BOINC_STATUS {
    int no_heartbeat;
    int suspended;
    int quit_request;
    int reread_init_data_file;
    int abort_request;
    double working_set_size;
    double max_working_set_size;
    int network_suspended;
} BOINC_STATUS;

You can get the current status using

void boinc_get_status(BOINC_STATUS*);