wiki:BossaImplementation

Context Navigation

Version 8 (modified by davea, 17 years ago) (diff)
--

Bossa reference manual

Bossa is a framework for distributed thinking applications. We'll describe Bossa using an example. The example shows users pictures of zeros or ones, and asks the user to identify the number.

Database tables

Until Bossa has good web-based administration tools, you'll often need to directly examine and modify its MySQL database, using the command-line tool 'mysql' or a web-based interface such as phpMyAdmin.

The database tables used by Bossa (in addition to BOINC's tables for users, teams, etc.) are as follows:

bossa_app:

field name	type	meaning
id	integer	row ID, assigned by MySQL
create_time	integer	row creation time
name	varchar(255)	short name (internal use; no spaces)
user_friendly_name	varchar(255)	user-visible name (spaces OK)
long_jobs	tinyint	nonzero if user can have > 1 active job
start_url	varchar(255)	name (relative to project URL) of start script
deprecated	tinyint	nonzero if deprecated (don't show)
info	text	information (typically encoded in JSON) such as the criteria for which users to issue jobs to

bossa_job:

field name	type	meaning
id	integer	row ID, assigned by MySQL
create_time	integer	row creation time
name	varchar(255)	a unique name for this job
app_id	integer	ID of bossa_app
info	text	job-specific info (file names etc.) typically JSON-encoded
batch	integer	batch number (use to group jobs)
time_estimate	integer	number of seconds this job is likely to take
time_limit	integer	give up if not completed after this number of seconds
more_needed	tinyint	nonzero if more completed instances of this job are needed
npending	integer	number of pending instances
nsuccess	integer	number of successfully completed instances
nsuccess_needed	integer	required number of successfully completed instances

bossa_job_inst:

field name	type	meaning
id	integer	row ID, assigned by MySQL
create_time	integer	row creation time
job_id	integer	ID of bossa_job
user_id	integer	ID of user
finish_time	integer	time when finished, or zero
info	text	outcome info (usually JSON-encoded)

bossa_app_user:

app_id	integer	ID of bossa_app
user_id	integer	ID of user
info	text	description of the user's skill or ranking at a given app, typically JSON-encoded

Bossa PHP classes

Bossa provides the following classes (in html/inc/bossa.inc and html/inc/bossa_db.inc):

BossaApp, BossaJob, BossaJobInst: These correspond to the above tables, and have fields corresponding to each database field. They offer functions to insert, look up, and modify database rows.
Bossa: Utility functions.

Creating a Bossa project

First, set up a BOINC server and create a project. You'll need PHP 5.2 or later (for JSON functions). Say your project is called test_project, your BOINC source directory is ~/boinc, and your BOINC projects directory is ~/projects.

Create Bossa's database tables as follows:

cd ~/boinc/db
mysql test_project < bossa_schema.sql
mysql test_project < bossa_constraints.sql

Create a Bossa application as follows:

cd ~/projects/test_project/html/ops
php bossa_setup_example.php

bossa_setup_example.php contains:

$ba = new BossaApp();
$ba->name = 'bossa_test';
$ba->user_friendly_name = 'Simple pattern recognition';
$ba->start_url = 'bossa_example.php';

if ($ba->insert($ba)) {
    echo "Added application '$ba->name'\n";
} else {
    echo "Couldn't add '$ba->name': ", mysql_error(), "\n";
}

You can edit this to change the application name and front-end script name, if you like.

Adding jobs

Typically you'll add jobs using a script. Here's an example (html/ops/bossa_make_jobs_example.php):

     1  <?php
     2
     3  require_once("../inc/bossa_db.inc");
     4  require_once("../inc/db.inc");
     5
     6  db_init();
     7
     8  function make_jobs() {
     9      $appname = 'bossa_test';
    10      $app = BossaApp::lookup_name($appname);
    11      if (!$app) {
    12          echo "Application $appname not found\n";
    13          exit(1);
    14      }
    15      $job = new BossaJob;
    16      $job->app_id = $app->id;
    17      $job->batch = 0;
    18      $job->time_estimate = 30;
    19      $job->time_limit = 600;
    20      $job->nsuccess_needed = 3;
    21      for ($i=0; $i<10; $i++) {
    22          $job->name = "job_$i";
    23          $info = null;
    24          $info->number = $i % 2;
    25          $job->info = json_encode($info);
    26          if (!$job->insert()) {
    27              echo "BossaJob::insert failed: ", mysql_error(), "\n";
    28              exit(1);
    29          }
    30      }
    31  }
    32
    33  make_jobs();
    34  echo "All done.\n";
    35
    36  ?>

This creates 10 jobs. Each job has an info field consisting of a JSON-encoded structure consisting of an integer (0 or 1).

Front-end scripts

You develop a front-end script to show a job instance to a user, and to handle a completed instance. It's handy to put both of these functions in a single file. A front-end script is called with the URL parameter bji set to a job instance ID. Here's an example (html/user/bossa_example.php):

     1  <?php
     2
     3  require_once("../inc/bossa.inc");
     4
     5  echo "foo";
     6
     7  // Bossa example.
     8  // Show the user an image and ask them whether it's a zero or one.
     9
    10  function show_job($bj, $bji) {
    11      if ($bji->finish_time) {
    12          error_page("You already finished this job");
    13      }
    14      $info = json_decode($bj->info);
    15      $img_url = "http://boinc.berkeley.edu/images/number_".$info->number.".jpg";
    16      echo "
    17          <form method=get action=bossa_example.php>
    18          <input type=hidden name=bji value=$bji->id>
    19          <img src=$img_url>
    20          <br>
    21          The picture shows a
    22          <br><input type=radio name=response value=0> zero
    23          <br><input type=radio name=response value=1> one
    24          <br><input type=radio name=response value=2 checked> not sure
    25          <br><br><input type=submit name=submit value=OK>
    26          </form>
    27      ";
    28  }
    29
    30  function handle_job_completion($bj, $bji) {
    31      $response = null;
    32      $response->number = get_int('response');
    33      $bji->info = json_encode($response);
    34      $bji->completed($bj);
    35
    36      // show another job immediately
    37      //
    38      Bossa::show_next_job($bj);
    39  }
    40
    41  Bossa::script_init($user, $bj, $bji);
    42
    43  if ($_GET['submit']) {
    44      handle_job_completion($bj, $bji);
    45  } else {
    46      show_job($bj, $bji);
    47  }
    48
    49  ?>

Line 41: Call a Bossa utility function to look up the job instance and make sure that it was issued to the logged-in user. The job instance, job, and user are returned.
Line 43: Branch according to whether we are showing a job or handling the completion of a job.
Line 14: If we're showing a job, decode its info structure to decide whether to show which picture to show.
Lines 17-18: Task completion will be handled by this script; arrange to pass the job instance ID.
Lines 31-33: Get the user's response, and encode it in JSON.
Line 34: Call a utility function that marks the job instance as completed and updates its database record.
Line 38: Call a utility function that gets another job (if one is available) and shows it to the user.

Download in other formats:

Plain Text