Changes between Version 40 and Version 41 of BasicApi
- Timestamp:
- Aug 10, 2012, 3:15:35 PM (12 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
BasicApi
v40 v41 5 5 Most of the functions have a C interface, 6 6 so that they can be used from programs written in C and other languages. 7 Unless otherwise specified, the functions return an integer error code; zero indicates success. 7 Unless otherwise specified, the functions return an integer error code; 8 zero indicates success. 8 9 To use the API include there header. 9 10 {{{ … … 94 95 == Checkpointing == #checkpointing 95 96 96 Computations that use a significant amount of time per work unit may want to periodically write the current state of the computation to disk. This is known as '''checkpointing'''. The state file must include everything required to start the computation again at the same place it was checkpointed. On startup, the application reads the state file to determine where to begin computation. If the BOINC client quits or exits, the computation can be restarted from the most recent checkpoint. 97 98 Frequency of checkpointing is a user preference (e.g. laptop users might want to checkpoint infrequently). An application must call 97 Long jobs may want to periodically 98 write the current state of the computation to disk. 99 This is known as '''checkpointing'''. 100 The checkpoint file must include everything required to restart the computation 101 at the same point. 102 On startup, the application reads the checkpoint file to determine where to begin computation. 103 If the BOINC client quits or exits, 104 the computation can be restarted from the most recent checkpoint. 105 106 Most applications are able to checkpoint only at specific points, 107 e.g. at the end the outer loop. 108 Whan the application is at such a point, it must call 99 109 100 110 {{{ … … 103 113 }}} 104 114 105 whenever it reaches a point where it is able to checkpoint. If this returns nonzero (True) then the application should checkpoint immediately (i.e., write the state file and flush all output files), then call 115 If this returns nonzero (True) then the application should checkpoint immediately 116 (i.e., write the state file and flush all output files), then call 106 117 107 118 {{{ … … 110 121 }}} 111 122 112 `boinc_time_to_checkpoint()` is fast, so it can be called frequently (hundreds or thousands of times a second). 123 `boinc_time_to_checkpoint()` is fast, 124 so it can be called frequently (hundreds or thousands of times a second). 125 126 '''boinc_time_to_checkpoint''' returns true only when sufficient time 127 has passed since the last checkpoint. 128 This minimum interval is the maximum of: 129 130 * A user preference 131 (e.g. laptop users might want to checkpoint infrequently). 132 * An optional application-supplied, specified by calling 133 134 {{{ 135 boinc_set_min_checkpoint_period(int nsecs); 136 }}} 113 137 114 138 If you're using replication, make sure your application generates the same results 115 139 regardless of where and how often it restarts. 116 140 This requires: 117 * In writing the checkpoint file, use conversion codes that don't lose precision; e.g., use %e for doubles. 118 * If your app uses random numbers, save and restore the state of the RNG. You can do this by surrounding every boinc_time_to_checkpoint() with the following: 141 * In writing the checkpoint file, use conversion codes that don't lose precision; 142 e.g., use %e for doubles. 143 * If your app uses random numbers, save and restore the state of the RNG. 144 If you use rand(), you can do this by surrounding every boinc_time_to_checkpoint() 145 with the following: 119 146 {{{ 120 147 int x = rand(); … … 135 162 }}} 136 163 137 Call these around code segments during which you don't want to be suspended or killed by the core client. Since r14694, critical sections are reentrant. This means that you can begin critical section multiple times, but each {{{begin}}} must have a matching {{{end}}} call. 164 Call these around code segments during which you don't want to be 165 suspended or killed by the core client. 166 Since r14694, critical sections are reentrant. 167 This means that you can begin critical section multiple times, 168 but each {{{begin}}} must have a matching {{{end}}} call. 138 169 139 170 '''NOTE:''' This is done automatically while checkpointing. … … 141 172 == Atomic file update == 142 173 143 To facilitate atomic checkpoint, an application can write to output and state files using the `MFILE` class. 174 To facilitate atomic checkpoint, 175 an application can write to output and state files using the `MFILE` class. 144 176 145 177 {{{ … … 157 189 }}} 158 190 159 MFILE buffers data in memory and writes to disk only on `flush()` or `close()`. This lets you write output files and state files more or less atomically. 191 MFILE buffers data in memory and writes to disk only on `flush()` or `close()`. 192 This lets you write output files and state files more or less atomically. 160 193 161 194 162 195 == Reporting progress == #progress 163 196 164 The core client GUI displays the percent done of workunits in progress. To keep this display current, an application should periodically call 197 The core client GUI displays the percent done of workunits in progress. 198 To keep this display current, an application should periodically call 165 199 166 200 {{{ … … 172 206 This function is fast and can be called frequently (once per second or more). 173 207 The sequence of arguments in successive calls should be non-decreasing. 174 An application should never 'reset' and start over if an error occurs; it should exit with an error code. 175 176 208 An application should never 'reset' and start over if an error occurs; 209 it should exit with an error code. 177 210 178 211 == Timing information == … … 195 228 == Standalone mode == #standalone 196 229 197 BOINC applications can be run in "standalone" mode for testing, or under the control of the BOINC client. 230 BOINC applications can be run in "standalone" mode for testing, 231 or under the control of the BOINC client. 198 232 You might want your application to behave differently in the two cases. 199 For example you might want to output debugging information if the application is running standalone. 200 To determine if the application is running in standalone mode or under the control of the BOINC client, call 233 For example you might want to output debugging information 234 if the application is running standalone. 235 To determine if the application is running in standalone mode or 236 under the control of the BOINC client, call 201 237 202 238 {{{ … … 205 241 }}} 206 242 207 This returns non-zero (True) if the application is running standalone, and zero (False) if the application is running under the control of the BOINC client. 243 This returns non-zero (True) if the application is running standalone, 244 and zero (False) if the application is running under the control of the BOINC client. 208 245 209 246 == Registering a timer handler == #timer
