The legion Reference Manual

Next: , Previous: , 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 Mon Aug 15 04:57:51 2022 GMT+0.

Table of Contents


1 Introduction

Legion

Build Status Coverage Status

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

Copyright

Copyright (c) 2015 Eitaro Fukamachi (e.arrows@gmail.com)

License

Licensed under the BSD 3-Clause License.


2 Systems

The main system appears first, followed by any subsystem dependency.


Next: , Previous: , 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
Source

legion.asd.


Next: , Previous: , Up: Systems   [Contents][Index]

2.2 legion/main

Author

Eitaro Fukamachi

License

BSD 3-Clause

Dependencies
Source

legion.asd.


Next: , Previous: , Up: Systems   [Contents][Index]

2.3 legion/worker

Author

Eitaro Fukamachi

License

BSD 3-Clause

Dependencies
Source

legion.asd.


Next: , Previous: , Up: Systems   [Contents][Index]

2.4 legion/queue

Author

Eitaro Fukamachi

License

BSD 3-Clause

Dependencies
  • cl-speedy-queue (system).
  • bordeaux-threads (system).
Source

legion.asd.


Next: , Previous: , Up: Systems   [Contents][Index]

2.5 legion/cluster

Author

Eitaro Fukamachi

License

BSD 3-Clause

Dependencies
Source

legion.asd.


Previous: , Up: Systems   [Contents][Index]

2.6 legion/error

Author

Eitaro Fukamachi

License

BSD 3-Clause

Source

legion.asd.


3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

3.1.1 legion/legion.asd

Source

legion.asd.

Parent Component

legion (system).

ASDF Systems

3.1.2 legion/main/file-type.lisp

Source

legion.asd.

Parent Component

legion/main (system).

Packages

legion.

Public Interface

3.1.3 legion/worker/file-type.lisp

Source

legion.asd.

Parent Component

legion/worker (system).

Packages

legion/worker.

Public Interface
Internals

3.1.4 legion/queue/file-type.lisp

Source

legion.asd.

Parent Component

legion/queue (system).

Packages

legion/queue.

Public Interface
Internals

3.1.5 legion/cluster/file-type.lisp

Source

legion.asd.

Parent Component

legion/cluster (system).

Packages

legion/cluster.

Public Interface
Internals

3.1.6 legion/error/file-type.lisp

Source

legion.asd.

Parent Component

legion/error (system).

Packages

legion/error.

Public Interface

legion-error (condition).


4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 legion/error

Source

file-type.lisp.

Use List

common-lisp.

Public Interface

legion-error (condition).


Next: , Previous: , Up: Packages   [Contents][Index]

4.2 legion/cluster

Source

file-type.lisp.

Use List

common-lisp.

Public Interface
Internals

Next: , Previous: , Up: Packages   [Contents][Index]

4.3 legion/worker

Source

file-type.lisp.

Use List

common-lisp.

Public Interface
Internals

Next: , Previous: , Up: Packages   [Contents][Index]

4.4 legion/queue

Source

file-type.lisp.

Use List

common-lisp.

Public Interface
Internals

Previous: , Up: Packages   [Contents][Index]

4.5 legion

Source

file-type.lisp.

Nickname

legion/main

Use List

common-lisp.

Public Interface

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


5.1.1 Ordinary functions

Function: dequeue (queue)
Package

legion/queue.

Source

file-type.lisp.

Function: enqueue (job queue)
Package

legion/queue.

Source

file-type.lisp.

Function: make-cluster (worker-num process-fn &rest initargs)
Package

legion.

Source

file-type.lisp.

Function: make-queue (&optional initial-size)
Package

legion/queue.

Source

file-type.lisp.

Function: make-worker (process-fn &rest initargs)
Package

legion.

Source

file-type.lisp.

Function: queue-count (queue)
Package

legion/queue.

Source

file-type.lisp.

Function: queue-empty-p (queue)
Package

legion/queue.

Source

file-type.lisp.

Function: wakenup (worker)
Package

legion/worker.

Source

file-type.lisp.

Function: worker-queue-count (worker)

Return the number of outstanding jobs.

Package

legion/worker.

Source

file-type.lisp.


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.

Package

legion/worker.

Source

file-type.lisp.

Methods
Method: add-job ((cluster cluster) job)
Source

file-type.lisp.

Method: add-job ((worker worker) val)
Generic Reader: cluster-status (object)
Package

legion/cluster.

Methods
Reader Method: cluster-status ((cluster cluster))

automatically generated reader method

Source

file-type.lisp.

Target Slot

status.

Generic Writer: (setf cluster-status) (object)
Package

legion/cluster.

Methods
Writer Method: (setf cluster-status) ((cluster cluster))

automatically generated writer method

Source

file-type.lisp.

Target Slot

status.

Generic Reader: cluster-workers (object)
Package

legion/cluster.

Methods
Reader Method: cluster-workers ((cluster cluster))

automatically generated reader method

Source

file-type.lisp.

Target Slot

workers.

Generic Function: fetch-job (worker)

Dequeue a value from WORKER’s queue. This returns multiple values – the job and a successed flag.

Package

legion/worker.

Source

file-type.lisp.

Methods
Method: fetch-job ((worker worker))
Generic Function: kill (worker)

Stop the given WORKER immediately.
It raises an error if the WORKER is not running.

Package

legion/worker.

Source

file-type.lisp.

Methods
Method: kill ((cluster cluster))
Source

file-type.lisp.

Method: kill ((worker worker))
Generic Function: process-job (worker job)
Package

legion/worker.

Source

file-type.lisp.

Methods
Method: process-job ((worker worker) job)
Generic Function: start (worker)

Start the given WORKER.
It raises an error if the WORKER is already running.

Package

legion/worker.

Source

file-type.lisp.

Methods
Method: start ((cluster cluster))
Source

file-type.lisp.

Method: start ((worker worker))
Generic Function: stop (worker)

Stop the given WORKER after processing its queued jobs. It raises an error if the WORKER is not running.

Package

legion/worker.

Source

file-type.lisp.

Methods
Method: stop ((cluster cluster))
Source

file-type.lisp.

Method: stop ((worker worker))
Generic Reader: worker-queue (object)
Package

legion/worker.

Methods
Reader Method: worker-queue ((worker worker))

automatically generated reader method

Source

file-type.lisp.

Target Slot

queue.

Generic Writer: (setf worker-queue) (object)
Package

legion/worker.

Methods
Writer Method: (setf worker-queue) ((worker worker))

automatically generated writer method

Source

file-type.lisp.

Target Slot

queue.

Generic Reader: worker-status (object)
Package

legion/worker.

Methods
Reader Method: worker-status ((worker worker))

automatically generated reader method

Source

file-type.lisp.

Target Slot

status.

Generic Writer: (setf worker-status) (object)
Package

legion/worker.

Methods
Writer Method: (setf worker-status) ((worker worker))

automatically generated writer method

Source

file-type.lisp.

Target Slot

status.


5.1.3 Standalone methods

Method: initialize-instance :after ((cluster cluster) &rest initargs &key workers &allow-other-keys)
Source

file-type.lisp.

Method: print-object ((object cluster) stream)
Source

file-type.lisp.

Method: print-object ((object worker) stream)
Source

file-type.lisp.


5.1.4 Conditions

Condition: legion-error
Package

legion/error.

Source

file-type.lisp.

Direct superclasses

error.


Next: , Previous: , Up: Public Interface   [Contents][Index]

5.1.5 Structures

Structure: queue
Package

legion/queue.

Source

file-type.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: primary
Readers

queue-primary.

Writers

(setf queue-primary).

Slot: buffered
Initform

(quote nil)

Readers

queue-buffered.

Writers

(setf queue-buffered).

Slot: lock
Initform

(bordeaux-threads:make-lock "queue lock")

Readers

queue-lock.

Writers

(setf queue-lock).


Previous: , Up: Public Interface   [Contents][Index]

5.1.6 Classes

Class: cluster
Package

legion/cluster.

Source

file-type.lisp.

Direct methods
Direct slots
Slot: status
Initform

:shutdown

Readers

cluster-status.

Writers

(setf cluster-status).

Slot: queue
Initform

(legion/queue:make-queue)

Initargs

:queue

Readers

cluster-queue.

Writers

(setf cluster-queue).

Slot: workers
Initform

(quote nil)

Initargs

:workers

Readers

cluster-workers.

Writers

This slot is read-only.

Class: worker
Package

legion/worker.

Source

file-type.lisp.

Direct methods
Direct slots
Slot: status
Initform

:shutdown

Readers

worker-status.

Writers

(setf worker-status).

Slot: queue
Initform

(legion/queue:make-queue)

Initargs

:queue

Readers

worker-queue.

Writers

(setf worker-queue).

Slot: process-fn
Initargs

:process-fn

Readers

worker-process-fn.

Writers

This slot is read-only.

Slot: thread
Readers

worker-thread.

Writers

This slot is read-only.

Slot: wait-lock
Initform

(bordeaux-threads:make-recursive-lock "wait-lock")

Readers

worker-wait-lock.

Writers

This slot is read-only.

Slot: wait-cond
Initform

(bordeaux-threads:make-condition-variable)

Readers

worker-wait-cond.

Writers

This slot is read-only.


5.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.1 Ordinary functions

Function: %make-queue (&key primary buffered lock)
Package

legion/queue.

Source

file-type.lisp.

Function: copy-queue (instance)
Package

legion/queue.

Source

file-type.lisp.

Function: extend (queue)
Package

legion/queue.

Source

file-type.lisp.

Function: need-to-extend-p (queue)
Package

legion/queue.

Source

file-type.lisp.

Function: need-to-tidy-p (queue)
Package

legion/queue.

Source

file-type.lisp.

Reader: queue-buffered (instance)
Writer: (setf queue-buffered) (instance)
Package

legion/queue.

Source

file-type.lisp.

Target Slot

buffered.

Reader: queue-lock (instance)
Writer: (setf queue-lock) (instance)
Package

legion/queue.

Source

file-type.lisp.

Target Slot

lock.

Function: queue-p (object)
Package

legion/queue.

Source

file-type.lisp.

Reader: queue-primary (instance)
Writer: (setf queue-primary) (instance)
Package

legion/queue.

Source

file-type.lisp.

Target Slot

primary.

Function: queue-to-enqueue (queue)
Package

legion/queue.

Source

file-type.lisp.

Function: tidy (queue)
Package

legion/queue.

Source

file-type.lisp.


5.2.2 Generic functions

Generic Reader: cluster-queue (object)
Package

legion/cluster.

Methods
Reader Method: cluster-queue ((cluster cluster))

automatically generated reader method

Source

file-type.lisp.

Target Slot

queue.

Generic Writer: (setf cluster-queue) (object)
Package

legion/cluster.

Methods
Writer Method: (setf cluster-queue) ((cluster cluster))

automatically generated writer method

Source

file-type.lisp.

Target Slot

queue.

Generic Function: run (worker)
Package

legion/worker.

Source

file-type.lisp.

Methods
Method: run ((worker worker))
Method: run :around ((worker worker))
Generic Reader: worker-process-fn (object)
Package

legion/worker.

Methods
Reader Method: worker-process-fn ((worker worker))

automatically generated reader method

Source

file-type.lisp.

Target Slot

process-fn.

Generic Reader: worker-thread (object)
Package

legion/worker.

Methods
Reader Method: worker-thread ((worker worker))

automatically generated reader method

Source

file-type.lisp.

Target Slot

thread.

Generic Reader: worker-wait-cond (object)
Package

legion/worker.

Methods
Reader Method: worker-wait-cond ((worker worker))

automatically generated reader method

Source

file-type.lisp.

Target Slot

wait-cond.

Generic Reader: worker-wait-lock (object)
Package

legion/worker.

Methods
Reader Method: worker-wait-lock ((worker worker))

automatically generated reader method

Source

file-type.lisp.

Target Slot

wait-lock.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %   (  
A   C   D   E   F   G   I   K   M   N   P   Q   R   S   T   W  
Index Entry  Section

%
%make-queue: Private ordinary functions

(
(setf cluster-queue): Private generic functions
(setf cluster-queue): Private generic functions
(setf cluster-status): Public generic functions
(setf cluster-status): Public generic functions
(setf queue-buffered): Private ordinary functions
(setf queue-lock): Private ordinary functions
(setf queue-primary): Private ordinary functions
(setf worker-queue): Public generic functions
(setf worker-queue): Public generic functions
(setf worker-status): Public generic functions
(setf worker-status): Public generic functions

A
add-job: Public generic functions
add-job: Public generic functions
add-job: Public generic functions

C
cluster-queue: Private generic functions
cluster-queue: Private generic functions
cluster-status: Public generic functions
cluster-status: Public generic functions
cluster-workers: Public generic functions
cluster-workers: Public generic functions
copy-queue: Private ordinary functions

D
dequeue: Public ordinary functions

E
enqueue: Public ordinary functions
extend: Private ordinary functions

F
fetch-job: Public generic functions
fetch-job: Public generic functions
Function, %make-queue: Private ordinary functions
Function, (setf queue-buffered): Private ordinary functions
Function, (setf queue-lock): Private ordinary functions
Function, (setf queue-primary): Private ordinary functions
Function, copy-queue: Private ordinary functions
Function, dequeue: Public ordinary functions
Function, enqueue: Public ordinary functions
Function, extend: Private ordinary functions
Function, make-cluster: Public ordinary functions
Function, make-queue: Public ordinary functions
Function, make-worker: Public ordinary functions
Function, need-to-extend-p: Private ordinary functions
Function, need-to-tidy-p: Private ordinary functions
Function, queue-buffered: Private ordinary functions
Function, queue-count: Public ordinary functions
Function, queue-empty-p: Public ordinary functions
Function, queue-lock: Private ordinary functions
Function, queue-p: Private ordinary functions
Function, queue-primary: Private ordinary functions
Function, queue-to-enqueue: Private ordinary functions
Function, tidy: Private ordinary functions
Function, wakenup: Public ordinary functions
Function, worker-queue-count: Public ordinary functions

G
Generic Function, (setf cluster-queue): Private generic functions
Generic Function, (setf cluster-status): Public generic functions
Generic Function, (setf worker-queue): Public generic functions
Generic Function, (setf worker-status): Public generic functions
Generic Function, add-job: Public generic functions
Generic Function, cluster-queue: Private generic functions
Generic Function, cluster-status: Public generic functions
Generic Function, cluster-workers: Public generic functions
Generic Function, fetch-job: Public generic functions
Generic Function, kill: Public generic functions
Generic Function, process-job: Public generic functions
Generic Function, run: Private generic functions
Generic Function, start: Public generic functions
Generic Function, stop: Public generic functions
Generic Function, worker-process-fn: Private generic functions
Generic Function, worker-queue: Public generic functions
Generic Function, worker-status: Public generic functions
Generic Function, worker-thread: Private generic functions
Generic Function, worker-wait-cond: Private generic functions
Generic Function, worker-wait-lock: Private generic functions

I
initialize-instance: Public standalone methods

K
kill: Public generic functions
kill: Public generic functions
kill: Public generic functions

M
make-cluster: Public ordinary functions
make-queue: Public ordinary functions
make-worker: Public ordinary functions
Method, (setf cluster-queue): Private generic functions
Method, (setf cluster-status): Public generic functions
Method, (setf worker-queue): Public generic functions
Method, (setf worker-status): Public generic functions
Method, add-job: Public generic functions
Method, add-job: Public generic functions
Method, cluster-queue: Private generic functions
Method, cluster-status: Public generic functions
Method, cluster-workers: Public generic functions
Method, fetch-job: Public generic functions
Method, initialize-instance: Public standalone methods
Method, kill: Public generic functions
Method, kill: Public generic functions
Method, print-object: Public standalone methods
Method, print-object: Public standalone methods
Method, process-job: Public generic functions
Method, run: Private generic functions
Method, run: Private generic functions
Method, start: Public generic functions
Method, start: Public generic functions
Method, stop: Public generic functions
Method, stop: Public generic functions
Method, worker-process-fn: Private generic functions
Method, worker-queue: Public generic functions
Method, worker-status: Public generic functions
Method, worker-thread: Private generic functions
Method, worker-wait-cond: Private generic functions
Method, worker-wait-lock: Private generic functions

N
need-to-extend-p: Private ordinary functions
need-to-tidy-p: Private ordinary functions

P
print-object: Public standalone methods
print-object: Public standalone methods
process-job: Public generic functions
process-job: Public generic functions

Q
queue-buffered: Private ordinary functions
queue-count: Public ordinary functions
queue-empty-p: Public ordinary functions
queue-lock: Private ordinary functions
queue-p: Private ordinary functions
queue-primary: Private ordinary functions
queue-to-enqueue: Private ordinary functions

R
run: Private generic functions
run: Private generic functions
run: Private generic functions

S
start: Public generic functions
start: Public generic functions
start: Public generic functions
stop: Public generic functions
stop: Public generic functions
stop: Public generic functions

T
tidy: Private ordinary functions

W
wakenup: Public ordinary functions
worker-process-fn: Private generic functions
worker-process-fn: Private generic functions
worker-queue: Public generic functions
worker-queue: Public generic functions
worker-queue-count: Public ordinary functions
worker-status: Public generic functions
worker-status: Public generic functions
worker-thread: Private generic functions
worker-thread: Private generic functions
worker-wait-cond: Private generic functions
worker-wait-cond: Private generic functions
worker-wait-lock: Private generic functions
worker-wait-lock: Private generic functions

Jump to:   %   (  
A   C   D   E   F   G   I   K   M   N   P   Q   R   S   T   W  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   F   L   P   Q   S   W  
Index Entry  Section

C
Class, cluster: Public classes
Class, worker: Public classes
cluster: Public classes
Condition, legion-error: Public conditions

F
File, file-type.lisp: The legion/main/file-type․lisp file
File, file-type.lisp: The legion/worker/file-type․lisp file
File, file-type.lisp: The legion/queue/file-type․lisp file
File, file-type.lisp: The legion/cluster/file-type․lisp file
File, file-type.lisp: The legion/error/file-type․lisp file
File, legion.asd: The legion/legion․asd file
file-type.lisp: The legion/main/file-type․lisp file
file-type.lisp: The legion/worker/file-type․lisp file
file-type.lisp: The legion/queue/file-type․lisp file
file-type.lisp: The legion/cluster/file-type․lisp file
file-type.lisp: The legion/error/file-type․lisp file

L
legion: The legion system
legion: The legion package
legion-error: Public conditions
legion.asd: The legion/legion․asd file
legion/cluster: The legion/cluster system
legion/cluster: The legion/cluster package
legion/error: The legion/error system
legion/error: The legion/error package
legion/main: The legion/main system
legion/queue: The legion/queue system
legion/queue: The legion/queue package
legion/worker: The legion/worker system
legion/worker: The legion/worker package

P
Package, legion: The legion package
Package, legion/cluster: The legion/cluster package
Package, legion/error: The legion/error package
Package, legion/queue: The legion/queue package
Package, legion/worker: The legion/worker package

Q
queue: Public structures

S
Structure, queue: Public structures
System, legion: The legion system
System, legion/cluster: The legion/cluster system
System, legion/error: The legion/error system
System, legion/main: The legion/main system
System, legion/queue: The legion/queue system
System, legion/worker: The legion/worker system

W
worker: Public classes

Jump to:   C   F   L   P   Q   S   W