Changes between Version 11 and Version 12 of BossaReference

Timestamp:

Jul 30, 2008, 10:14:08 AM (16 years ago)

Author:

davea

Comment:

--

BossaReference

@@ -4 +4 @@
  * A Bossa project has one or more '''applications'''.
  * A application has a dynamic set of '''jobs'''.
- * An application has a dynamic set of '''batches''', which are used to group jobs.
- * Each job has a set of '''job instances''', in progress or completed.
+ * An application has a dynamic set of '''batches''' (groups of jobs).
+ * Each job has a set of '''job instances'''.
  * A '''user''' is a person who volunteers to perform jobs.
 
-Each of these is represented by a table in a MySQL database.
+Each has a corresponding table in a MySQL database.
 
-Each application has an associated "time estimate" - shown to user - and
-"time limit"; if an instance is not completed within the time limit,
+Each application has an associated "time estimate" and "time limit";
+if an instance is not completed within the time limit,
 is is considered "timed out".
 
@@ -17 +17 @@
 These are jobs for which the answer is known in advance;
 their purpose is to estimate the accuracy of each user.
-Each application has a '''calibration job fraction''';
-this is the probability with which calibration jobs are assigned.
+Each application has a '''calibration job fraction''':
+the probability with which calibration jobs are assigned.
 
 Each job has a '''state''', one of:
@@ -34 +34 @@
 Jobs are assigned to users in order of decreasing priority.
 
-Each job, job instance, and user has an associated '''app data''' - a PHP structure
+Each job, job instance, and user has associated '''opaque data''' - a PHP structure
 whose contents are determined by the project, not by Bossa.
 These structures are stored in the database.
 
-For jobs, the app data typically contains the information needed to display
+For jobs, the opaque data typically contains the information needed to display
 the job to a user - e.g., the name of an image file.
 For calibration jobs, it would also contain the correct answer.
 
-For instances, the app data typically contains the user's response to the job.
+For instances, the opaque data typically contains the user's response to the job.
 
-For users, the app data typically contains a representation of the
+For users, the opaque data typically contains a representation of the
 user's "skill", possibly including:
 
@@ -51 +51 @@
  * their performance based on validation
 
-If a project has multiple applications, it should keep separate
-data for each applications.
+If a project has multiple applications, it could contain separate
+data for each application.
 
-For some applications it is desirable to group users into discrete '''levels''',
-with each level performing a variant of the job.
-The level of a user is represented as an integer in a fixed range.
+For some applications it is desirable to group users into '''levels''' (0, 1, ...).
+For example, level 0 might be average users, and level 1, expert users.
 
-When levels are used, each job has not a single priority,
-but rather a vector of priorities, one per level.
+When levels are used, each job has a vector of priorities, one per level.
 Jobs are assigned to a particular user in order of decreasing
 priority for that user's level.
 
-== API for job creation ==
+== Job creation API ==
 
 {{{
@@ -82 +80 @@
 Returns true on success.
 
-== Application functions ==
+== Callback functions ==
 
 Each application must define a set of functions, listed below.
@@ -129 +127 @@
 }}}
 
-Return a string summarizing the app data for an instance.
+Return a string summarizing the opaque data for an instance.
 
 {{{
@@ -135 +133 @@
 }}}
 
-Return a string summarizing the app data for a user.
+Return a string summarizing the opaque data for a user.
 
-== API for application functions ==
+== Bossa API ==
 
 The interface of "job" objects is
 
 {{{
-mixed get_info()
+mixed get_opaque_data()
 array get_instances()
+   // return array of all instances
 array get_finished_instances()
+   // return array of finished instances
 bool set_priority(float $priority [int $level]}
-bool update_state(int $state)
+   // set priority for the given level (default level is zero)
+bool set_state(int $state)
 }}}
 
@@ -152 +153 @@
 
 {{{
-bool set_priority(float $priority)
-bool update_info(mixed $app_data)
+bool set_opaque_data(mixed $data)
+mixed get_opaque_data()
+object get_user()
+   // return user to whom this instance was issued
 }}}
 
@@ -160 +163 @@
 
 {{{
-mixed get_info()
-bool update_info(mixed $app_data)
+mixed get_opaque_data()
+bool set_opaque_data(mixed $data)
 bool set_level(int $level)
 }}}