= Options and status APIs =

== Setting options ==

The following runtime system 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;
};

BOINC_OPTIONS options;
boinc_options_defaults(options);   // set defaults
options.main_program = 0;          // set values as needed
...
int boinc_init_options(&options);
}}}

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 [CompoundApps 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).

== 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*);
}}}