job-worker
![[Picture of an egg]](egg.jpg)
Background Job/Worker Associates
NOTE: This is a work in progress.
Runs a background task (Associate) upon an event (Circumstance). An Associate is a work assignment - a composition of a Chore and a Laborer. A Circumstance is something that can detect a state change and return any facts about the state change.
The actual task is defined by a Chore, which needs to be performed not at all, once, some number of times, or always. The chore is handled by a Laborer. Via the associate a chore and a laborer can query each other for cooperative task completion.
Associates, Chores, and Laborers have an optional, fixed at construction time, number of arbitrary object slots available. As a convenience, when chore/laborer cooperation is not required, so-called 'pass-thru' versions can be constructed.
The 'pass-thru' chore doesn't have any extra state, and is performed by a 0-arity procedure. The 'pass-thru' laborer doesn't have any extra state, and just calls the associated chore's procedure.
Returns a fresh circumstance object.
| ID | The name of the circumstance. A symbol. |
| WAITER | Event detection. A procedure. Should return an object representing any facts about the particular circumstance detected. |
| DATA | Data for this circumstance. 0 or more objects. Reference is indexed from 0. |
Is this OBJECT an circumstance?
Returns the field value.
Returns the field value.
Returns the field value.
Sets the field value.
Sets all the field data.
Returns a fresh chore object.
| ID | The name of the chore. A symbol. |
| AMOUNT | Number of times to perform this chore. A positive integer, can be +inf.0. |
| CIRCUMSTANCE | What triggers this chore. An circumstance. |
| ACTION | (-> ASSOCIATE FACTS UNDEFINED). A procedure taking the assigned position and the facts about the particular triggering circumstance. |
| DATA | Data for this chore. 0 or more objects. Reference is indexed from 0 |
Returns a fresh chore object, with a generated id.
Returns a fresh chore object, with an action around THUNK, a procedure of 0-arity, which ignores away any arguments.
Is this OBJECT a chore?
Returns the field value.
Returns the field value.
Returns the field value.
Returns the field value.
Returns the field value.
Sets the field value.
Sets all the field data.
Returns a fresh laborer object.
| ID | The name of the laborer. A symbol. |
| ACTION | (-> ASSOCIATE FACTS UNDEFINED). A procedure taking the assigned position and the facts about the particular triggering circumstance. Must invoke the associated chore action with assigned position and circumstance facts. |
| DATA | Data for this laborer. 0 or more objects. Reference is indexed from 0 |
Returns a fresh laborer object, with a generated id.
Returns a fresh laborer object which directly invokes the associated chore action.
Is this OBJECT a laborer?
Returns the field value.
Returns the field value.
Returns the field value.
Sets the field value.
Sets all the field data.
Gets or sets the default QUANTUM milliseconds for associates.
Returns a fresh assigned position object.
| CHORE | The chore to perform. A chore. |
| LABORER | The laborer to perform the chore. A laborer. |
| DATA | Data for this associate. 0 or more objects. |
Is this OBJECT an associate?
Returns the field value.
Returns the field value.
Returns the field value.
The circumstance for the associated chore.
The amount of work for the associated chore.
The remaining amount of work to perform.
Sets the remaining amount of work to perform to the amount of work of the associated chore.
Returns the field value.
Sets the field value.
Sets all the field data.
Returns the field value.
Starts the associate running. Any subsequent attempt to start the associate will be silently ignored.
Causes the associate to finish work early. Can be called from a chore or laborer action.
Causes the associate to finish work early, after one more work session. Can be called from a chore or laborer action.
The associate's time quantum.
Set the associate's time quantum.
Raises or lowers the associate's time quantum by the BIAS milliseconds amount, or by the FACTOR percentage flonum value.
Schedules the associate for "reaping."
Unblocks a blocked associate.
Abnormally terminates the associate.
Suspends the associate.
Resumes a suspended associate.
Gets or sets the default QUANTUM milliseconds for the associate "reaper."
The reaper is the background task that handles waiting for the associates to finish. The reaper itself is automatically reaped upon process exit.
Gets or sets whether associates are automatically scheduled for "reaping" upon start.
Should automatic reaping be turned off it is the users' responsibility to explicitly reap the associate. See associate-reap! above.
Normally the reaper is not started until needed. However, chaining the implicit-exit-handler with code that attempts to force an associate reap will cause problems with the delayed reaper start. So this must be called before performing any such chaining.
Creates and starts a timeout associate. Returns the associate.
| ID | The name of the chore. A symbol. |
| THUNK | The action to perform upon timeout. A procedure of 0-arity. |
| SECONDS | Perform chore every how many seconds. A positive number. |
| LABORER | Who should perform the chore. A laborer. Defaults to a 'pass-thru' laborer. |
Returns a timeout associate.
Returns a timeout chore.
Returns a timeout circumstance.
Copyright (c) 2005, Kon Lovett. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the Software), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.