Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
The legion Reference Manual
This is the legion Reference Manual, version 0.1.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Tue Nov 15 06:11:27 2022 GMT+0.
Table of Contents
Next: Systems, Previous: The legion Reference Manual, Up: The legion Reference Manual [Contents][Index]
1 Introduction
Legion
Jesus asked him, "What is your name?" And he said, "My name is Legion, for we are many." ── Gospel of Mark chapter 5, verse 9
Usage
Worker
(defparameter *worker*
(make-worker
(lambda (job)
(format t "Processed: ~S~%" job))))
(start *worker*)
(add-job *worker* 10)
(add-job *worker* "Hi")
(stop *worker*)
Cluster
(defparameter *cluster*
(make-cluster 4
(lambda (job)
(format t "Processed: ~S~%" job))))
(start *cluster*)
(add-job *cluster* 10)
(add-job *cluster* "Hi")
(stop *cluster*)
NOTE: Cluster doesn't guarantee the order of processing jobs.
Functions
[Class] worker
Base class of workers.
You can specify the value by specifying :queue.
[Function] (worker-status worker)
Return the worker's status which is specifically one of :running, :idle, :shutting and :shutdown.
[Function] (worker-queue-count worker)
Return the number of outstanding jobs of the worker.
[Method] (start worker-or-cluster)
Start the given worker or cluster to process jobs.
[Method] (stop worker-or-cluster)
Stop the given worker or cluster after processing its queued jobs.
[Method] (kill worker-or-cluster)
Stop the given worker or cluster immediately (outstanding jobs will be remained in its queue).
[Method] (add-job worker-or-cluster val)
Enqueue a new job val which will be passed to a function specified for make-worker.
[Method] (fetch-job worker) => val, existsp
Dequeue a job from worker's queue.
[Class] cluster
Base class of clusters.
[Function] (cluster-status cluster)
Return the cluster's status which is one of :running, :shutting and :shutdown.
[Function] (start-cluster cluster)
Start workers of cluster.
[Function] (cluster-workers cluster) => workers-array
Return workers of cluster in simple-array.
Author
- Eitaro Fukamachi (e.arrows@gmail.com)
Copyright
Copyright (c) 2015 Eitaro Fukamachi (e.arrows@gmail.com)
License
Licensed under the BSD 3-Clause License.
Next: Files, Previous: Introduction, Up: The legion Reference Manual [Contents][Index]
2 Systems
The main system appears first, followed by any subsystem dependency.
Next: legion/main, Previous: Systems, Up: Systems [Contents][Index]
2.1 legion
Simple worker threads with a queue.
- Author
Eitaro Fukamachi
- License
BSD 3-Clause
- Version
0.1.1
- Dependencies
- vom (system).
- legion/main (system).
- Source
Next: legion/worker, Previous: legion, Up: Systems [Contents][Index]
2.2 legion/main
- Author
Eitaro Fukamachi
- License
BSD 3-Clause
- Dependencies
- legion/worker (system).
- legion/cluster (system).
- legion/error (system).
- Source
Next: legion/queue, Previous: legion/main, Up: Systems [Contents][Index]
2.3 legion/worker
- Author
Eitaro Fukamachi
- License
BSD 3-Clause
- Dependencies
- legion/queue (system).
- bordeaux-threads (system).
- Source
Next: legion/cluster, Previous: legion/worker, Up: Systems [Contents][Index]
2.4 legion/queue
- Author
Eitaro Fukamachi
- License
BSD 3-Clause
- Dependencies
- cl-speedy-queue (system).
- bordeaux-threads (system).
- Source
Next: legion/error, Previous: legion/queue, Up: Systems [Contents][Index]
2.5 legion/cluster
- Author
Eitaro Fukamachi
- License
BSD 3-Clause
- Dependencies
- legion/worker (system).
- legion/queue (system).
- legion/error (system).
- bordeaux-threads (system).
- Source
Previous: legion/cluster, Up: Systems [Contents][Index]
2.6 legion/error
- Author
Eitaro Fukamachi
- License
BSD 3-Clause
- Source
Next: Packages, Previous: Systems, Up: The legion Reference Manual [Contents][Index]
3 Files
Files are sorted by type and then listed depth-first from the systems components trees.
3.1 Lisp
- legion/legion.asd
- legion/main/file-type.lisp
- legion/worker/file-type.lisp
- legion/queue/file-type.lisp
- legion/cluster/file-type.lisp
- legion/error/file-type.lisp
Next: legion/main/file-type.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
3.1.1 legion/legion.asd
- Source
- Parent Component
legion (system).
- ASDF Systems
Next: legion/worker/file-type.lisp, Previous: legion/legion.asd, Up: Lisp [Contents][Index]
3.1.2 legion/main/file-type.lisp
- Source
- Parent Component
legion/main (system).
- Packages
- Public Interface
- make-cluster (function).
- make-worker (function).
Next: legion/queue/file-type.lisp, Previous: legion/main/file-type.lisp, Up: Lisp [Contents][Index]
3.1.3 legion/worker/file-type.lisp
- Source
- Parent Component
legion/worker (system).
- Packages
- Public Interface
- add-job (generic function).
- fetch-job (generic function).
- kill (generic function).
- print-object (method).
- process-job (generic function).
- start (generic function).
- stop (generic function).
- wakenup (function).
- worker (class).
- worker-queue (reader method).
- (setf worker-queue) (writer method).
- worker-queue-count (function).
- worker-status (reader method).
- (setf worker-status) (writer method).
- Internals
- run (generic function).
- worker-process-fn (reader method).
- worker-thread (reader method).
- worker-wait-cond (reader method).
- worker-wait-lock (reader method).
Next: legion/cluster/file-type.lisp, Previous: legion/worker/file-type.lisp, Up: Lisp [Contents][Index]
3.1.4 legion/queue/file-type.lisp
- Source
- Parent Component
legion/queue (system).
- Packages
- Public Interface
- dequeue (function).
- enqueue (function).
- make-queue (function).
- queue (structure).
- queue-count (function).
- queue-empty-p (function).
- Internals
- %make-queue (function).
- copy-queue (function).
- extend (function).
- need-to-extend-p (function).
- need-to-tidy-p (function).
- queue-buffered (reader).
- (setf queue-buffered) (writer).
- queue-lock (reader).
- (setf queue-lock) (writer).
- queue-p (function).
- queue-primary (reader).
- (setf queue-primary) (writer).
- queue-to-enqueue (function).
- tidy (function).
Next: legion/error/file-type.lisp, Previous: legion/queue/file-type.lisp, Up: Lisp [Contents][Index]
3.1.5 legion/cluster/file-type.lisp
- Source
- Parent Component
legion/cluster (system).
- Packages
- Public Interface
- add-job (method).
- cluster (class).
- cluster-status (reader method).
- (setf cluster-status) (writer method).
- cluster-workers (reader method).
- initialize-instance (method).
- kill (method).
- print-object (method).
- start (method).
- stop (method).
- Internals
- cluster-queue (reader method).
- (setf cluster-queue) (writer method).
Previous: legion/cluster/file-type.lisp, Up: Lisp [Contents][Index]
3.1.6 legion/error/file-type.lisp
- Source
- Parent Component
legion/error (system).
- Packages
- Public Interface
legion-error (condition).
Next: Definitions, Previous: Files, Up: The legion Reference Manual [Contents][Index]
4 Packages
Packages are listed by definition order.
Next: legion/cluster, Previous: Packages, Up: Packages [Contents][Index]
4.1 legion/error
- Source
- Use List
common-lisp.
- Public Interface
legion-error (condition).
Next: legion/worker, Previous: legion/error, Up: Packages [Contents][Index]
4.2 legion/cluster
- Source
- Use List
common-lisp.
- Public Interface
- cluster (class).
- cluster-status (generic reader).
- (setf cluster-status) (generic writer).
- cluster-workers (generic reader).
- Internals
- cluster-queue (generic reader).
- (setf cluster-queue) (generic writer).
Next: legion/queue, Previous: legion/cluster, Up: Packages [Contents][Index]
4.3 legion/worker
- Source
- Use List
common-lisp.
- Public Interface
- add-job (generic function).
- fetch-job (generic function).
- kill (generic function).
- process-job (generic function).
- start (generic function).
- stop (generic function).
- wakenup (function).
- worker (class).
- worker-queue (generic reader).
- (setf worker-queue) (generic writer).
- worker-queue-count (function).
- worker-status (generic reader).
- (setf worker-status) (generic writer).
- Internals
- run (generic function).
- worker-process-fn (generic reader).
- worker-thread (generic reader).
- worker-wait-cond (generic reader).
- worker-wait-lock (generic reader).
Next: legion, Previous: legion/worker, Up: Packages [Contents][Index]
4.4 legion/queue
- Source
- Use List
common-lisp.
- Public Interface
- dequeue (function).
- enqueue (function).
- make-queue (function).
- queue (structure).
- queue-count (function).
- queue-empty-p (function).
- Internals
- %make-queue (function).
- copy-queue (function).
- extend (function).
- need-to-extend-p (function).
- need-to-tidy-p (function).
- queue-buffered (reader).
- (setf queue-buffered) (writer).
- queue-lock (reader).
- (setf queue-lock) (writer).
- queue-p (function).
- queue-primary (reader).
- (setf queue-primary) (writer).
- queue-to-enqueue (function).
- tidy (function).
Previous: legion/queue, Up: Packages [Contents][Index]
4.5 legion
- Source
- Nickname
legion/main
- Use List
common-lisp.
- Public Interface
- make-cluster (function).
- make-worker (function).
Next: Indexes, Previous: Packages, Up: The legion Reference Manual [Contents][Index]
5 Definitions
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
5.1 Public Interface
Next: Generic functions, Previous: Public Interface, Up: Public Interface [Contents][Index]
5.1.1 Ordinary functions
- Function: dequeue (queue) ¶
-
- Package
- Source
- Function: enqueue (job queue) ¶
-
- Package
- Source
- Function: make-cluster (worker-num process-fn &rest initargs) ¶
-
- Package
- Source
- Function: make-queue (&optional initial-size) ¶
-
- Package
- Source
- Function: make-worker (process-fn &rest initargs) ¶
-
- Package
- Source
- Function: queue-count (queue) ¶
-
- Package
- Source
- Function: queue-empty-p (queue) ¶
-
- Package
- Source
- Function: wakenup (worker) ¶
-
- Package
- Source
- Function: worker-queue-count (worker) ¶
-
Return the number of outstanding jobs.
- Package
- Source
Next: Standalone methods, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
5.1.2 Generic functions
- Generic Function: add-job (worker val) ¶
-
Enqueue VAL to WORKER’s queue. This returns WORKER when the queueing has been succeeded; otherwise NIL is returned.
- Generic Reader: cluster-status (object) ¶
- Generic Writer: (setf cluster-status) (object) ¶
- Generic Reader: cluster-workers (object) ¶
- Generic Function: fetch-job (worker) ¶
-
Dequeue a value from WORKER’s queue. This returns multiple values – the job and a successed flag.
- Package
- Source
- Methods
- Generic Function: kill (worker) ¶
-
Stop the given WORKER immediately.
It raises an error if the WORKER is not running.
- Generic Function: process-job (worker job) ¶
-
- Package
- Source
- Methods
- Generic Function: start (worker) ¶
-
Start the given WORKER.
It raises an error if the WORKER is already running.
- Generic Function: stop (worker) ¶
-
Stop the given WORKER after processing its queued jobs. It raises an error if the WORKER is not running.
- Generic Reader: worker-queue (object) ¶
- Generic Writer: (setf worker-queue) (object) ¶
- Generic Reader: worker-status (object) ¶
- Generic Writer: (setf worker-status) (object) ¶
Next: Conditions, Previous: Generic functions, Up: Public Interface [Contents][Index]
5.1.3 Standalone methods
- Method: initialize-instance :after ((cluster cluster) &rest initargs &key workers &allow-other-keys) ¶
-
- Source
Next: Structures, Previous: Standalone methods, Up: Public Interface [Contents][Index]
5.1.4 Conditions
- Condition: legion-error ¶
-
- Package
- Source
- Direct superclasses
error.
Next: Classes, Previous: Conditions, Up: Public Interface [Contents][Index]
5.1.5 Structures
- Structure: queue ¶
Previous: Structures, Up: Public Interface [Contents][Index]
5.1.6 Classes
- Class: cluster ¶
- Class: worker ¶
-
- Package
- Source
- Direct methods
- Direct slots
- Slot: status ¶
-
- Initform
:shutdown
- Readers
- Writers
- Slot: queue ¶
-
- Initform
(legion/queue:make-queue)
- Initargs
:queue
- Readers
- Writers
- Slot: process-fn ¶
-
- Initargs
:process-fn
- Readers
- Writers
This slot is read-only.
- Slot: thread ¶
-
- Readers
- Writers
This slot is read-only.
- Slot: wait-lock ¶
-
- Initform
(bordeaux-threads:make-recursive-lock "wait-lock")
- Readers
- Writers
This slot is read-only.
- Slot: wait-cond ¶
-
- Initform
(bordeaux-threads:make-condition-variable)
- Readers
- Writers
This slot is read-only.
Previous: Public Interface, Up: Definitions [Contents][Index]
5.2 Internals
Next: Generic functions, Previous: Internals, Up: Internals [Contents][Index]
5.2.1 Ordinary functions
- Function: %make-queue (&key primary buffered lock) ¶
-
- Package
- Source
- Function: copy-queue (instance) ¶
-
- Package
- Source
- Function: extend (queue) ¶
-
- Package
- Source
- Function: need-to-extend-p (queue) ¶
-
- Package
- Source
- Function: need-to-tidy-p (queue) ¶
-
- Package
- Source
- Reader: queue-buffered (instance) ¶
- Writer: (setf queue-buffered) (instance) ¶
-
- Package
- Source
- Target Slot
- Reader: queue-lock (instance) ¶
- Writer: (setf queue-lock) (instance) ¶
-
- Package
- Source
- Target Slot
lock.
- Function: queue-p (object) ¶
-
- Package
- Source
- Reader: queue-primary (instance) ¶
- Writer: (setf queue-primary) (instance) ¶
-
- Package
- Source
- Target Slot
- Function: queue-to-enqueue (queue) ¶
-
- Package
- Source
- Function: tidy (queue) ¶
-
- Package
- Source
Previous: Ordinary functions, Up: Internals [Contents][Index]
5.2.2 Generic functions
- Generic Reader: cluster-queue (object) ¶
- Generic Writer: (setf cluster-queue) (object) ¶
- Generic Function: run (worker) ¶
-
- Package
- Source
- Methods
- Generic Reader: worker-process-fn (object) ¶
- Generic Reader: worker-thread (object) ¶
- Generic Reader: worker-wait-cond (object) ¶
- Generic Reader: worker-wait-lock (object) ¶
Previous: Definitions, Up: The legion Reference Manual [Contents][Index]
Appendix A Indexes
A.2 Functions
| Jump to: | %
(
A C D E F G I K M N P Q R S T W |
|---|
| Jump to: | %
(
A C D E F G I K M N P Q R S T W |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
A.3 Variables
| Jump to: | B L P Q S T W |
|---|
| Jump to: | B L P Q S T W |
|---|
A.4 Data types
| Jump to: | C F L P Q S W |
|---|
| Jump to: | C F L P Q S W |
|---|