Changes between Version 25 and Version 26 of WrapperApp


Ignore:
Timestamp:
Jun 18, 2008, 11:51:55 AM (16 years ago)
Author:
davea
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WrapperApp

    v25 v26  
    11= Legacy applications =
    22
    3 A '''legacy application''' is one which doesn't use the BOINC API
     3A 'legacy application' is one which doesn't use the BOINC API
    44(for example, because the source code is not available).
    5 Such applications can be run under BOINC using a 'wrapper application' supplied by BOINC.
    6 The wrapper handles all communication with the core client,
    7 and runs the legacy application as a subprocess:
     5Such applications can be run under BOINC using a '''wrapper''' program supplied by BOINC.
     6The wrapper runs legacy applications as subprocesses,
     7and handles all communication with the core client
     8(e.g., to report CPU time and fraction done).
    89
    910[[Image(http://boinc.berkeley.edu/wrapper.png)]]
    1011
    11 The wrapper program (called '''wrapper''') is in [ExampleApps boinc_samples].
     12The '''wrapper''' program is in [ExampleApps boinc_samples].
    1213It reads a file with [BoincFiles logical name] 'job.xml'.
    1314This file has the format:
    … …  
    2829}}}
    2930
    30 The job file specifies a sequence of tasks.
     31The job file describes a sequence of tasks.
    3132The descriptor for each task includes:
    3233
    3334 '''application''':: The logical name of the application, or 'worker program'.
    3435 '''stdin_filename''', '''stdout_filename''', '''stderr_filename''':: The logical names of the files to which stdin, stdout, and stderr are to be connected (if any).
    35  '''command_line''':: command-line arguments to be passed to the worker program. '''wrapper''' itself may be passed command-line arguments (specified in the workunit template); these are passed to each of the worker programs after those specified in the job file.
     36 '''command_line''':: command-line arguments to be passed to the worker program.  '''wrapper''' itself may be passed command-line arguments (specified in the [ WorkGeneration#templates input template); these are passed to each worker program after those specified in the job file.
    3637 '''weight''':: the contribution of each task to the overall fraction done is proportional to its weight (floating-point, default 1).  For example, if your job has tasks A and B, and A uses 100 times more CPU time than B, set A.weight=100 and B.weight=1.
    3738 '''checkpoint_filename''':: the name of the checkpoint file used by the app, if any.  When this is modified, the wrapper assumes that a checkpoint has been completed and notifies the core client.
    38 
    39 Worker programs must exit with zero status; nonzero values are interpreted as error codes by the wrapper.
    4039
    4140The job file can specify multiple tasks.
    … …  
    4746Notes:
    4847
    49  * In the following example, the job file is part of the application version (it's the same between workunits).  Alternatively, it can be part of the workunit (e.g. if its command line elements differ between workunits).  This requires that you use the same worker program names for all platforms.
     48 * Normally the job file is part of the application version (it's the same between workunits).  Alternatively, it can be part of the workunit (e.g. if its command line elements differ between workunits).  This requires that you use the same worker program logical names for all platforms.
    5049 * Files opened directly by a worker program must have the <copy_file/> tag. This requires version 5.5 or higher of the BOINC core client (you can specify this limit at either the [AppVersion application] or [ProjectOptions#Clientcontrol project] level.
    51  * If you run wrapper in standalone mode (while debugging), you must provide input files with the proper logical, not physical, names.
     50 * Worker programs must exit with zero status; nonzero values are interpreted as errors by the wrapper.
     51 * If you run '''wrapper''' in standalone mode (while debugging), you must provide input files with the proper logical, not physical, names.
     52
     53== Physical file management ==
     54
     55You can use the wrapper together with [PhysicalFileManagement physical file management],
     56where you directly access files in your project directory.
     57For example, you could create a job whose first task unpacks a zip file
     58into the project directory,
     59and whose subsequent tasks access these files.
     60
     61The support for this is:
     62
     63 * If a worker program name begins with "$PROJECT_DIR", that substring is replaced with the project directory, and the name is treated as a physical name.
     64 * In task command lines, "$PROJECT_DIR" is replaced with the project directory.
    5265
    5366== Example ==
    5467
    55 Here's an example that shows how to use this mechanism.
     68Here's an example that shows how to use the legacy application mechanism.
    5669We assume that you have already [MakeProject created a project] with root directory PROJECT/.
    5770
    58  * Compile the program 'worker' from the [ExampleApps boinc_samples] tree, producing (say) 'worker_5.10_windows_intelx86.exe'. This is the legacy app. If reads from stdin and writes to stdout; it also opens and reads a file 'in', and opens and writes a file 'out'. It takes one command-line argument: the number of CPU seconds to use.
    59  * Compile the program 'wrapper' from the [ExampleApps boinc_samples] tree, producing (say) 'wrapper_5.10_windows_intelx86.exe'. This program executes your legacy application, and acts as a proxy for it (to report CPU time etc.).
     71 * Compile the program 'worker' from the [ExampleApps boinc_samples] tree, producing (say) 'worker_5.10_windows_intelx86.exe'. This is the legacy app. It reads from stdin and writes to stdout; it also opens and reads a file 'in', and opens and writes a file 'out'. It takes one command-line argument: the number of CPU seconds to use.
     72 * Compile the program 'wrapper' from the [ExampleApps boinc_samples] tree, producing (say) 'wrapper_5.10_windows_intelx86.exe'.
    6073 * [AppVersion Create an application] named 'worker' and a corresponding directory 'PROJECT/apps/worker'. In this directory, create a directory 'wrapper_5.10_windows_intelx86.exe'. Put the files 'wrapper_5.10_windows_intelx86.exe', and 'worker_5.10_windows_intelx86.exe' there.  Rename the latter file to 'worker=worker_5.10_windows_intelx86.exe' (this gives it the logical name 'worker').
    6174 * In the same directory, create a file 'job.xml=job_1.12.xml' (1.12 is a version number) containing
    … …  
    7083</job_desc>
    7184}}}
    72  This file (which has logical name 'job.xml' and physical name 'job_1.12.xml') is read by 'wrapper'; it tells it the name of the legacy program, what files to connect to its stdin/stdout, and a command line.
     85 This file (which has logical name 'job.xml' and physical name 'job_1.12.xml') is read by 'wrapper'; it tells it the name of the worker program, what files to connect to its stdin/stdout, and a command line.
    7386 * In the 'PROJECT/templates' directory create a workunit template file called 'worker_wu':
    7487{{{
    … …  
    146159||wrapper_5.10_windows_intelx86.exe||wrapper_5.10_windows_intelx86.exe (link to project/wrapper_5.10_windows_intelx86.exe) ||
    147160
    148 The wrapper program executes the worker, connecting its stdin to project/input2 and its stdout to project/worker_nodelete_0. The worker program opens 'in' for reading and 'out' for writing.
     161The wrapper program executes the worker, connecting its stdin to project/input2 and its stdout to project/worker_nodelete_0.
     162The worker program opens 'in' for reading and 'out' for writing.
    149163
    150 When the worker program finishes, the wrapper sees this and exits. Then the BOINC core client copies slot/out to project/worker_nodelete_1.
     164When the worker program finishes, the wrapper sees this and exits.
     165Then the BOINC core client copies slot/out to project/worker_nodelete_1.
    151166