The cl-gserver Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-gserver Reference Manual

This is the cl-gserver Reference Manual, version 0.4.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 10:15:46 2020 GMT+0.


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

1 Introduction

Cl-GServer

GServer is an Erlang inspired GenServer. It is meant to encapsulate state, but also to execute async operations.
Encapsulating state also means that it gives a safe facility to update state within a multi-threaded environment without having you to worry about maintaining access to state.

State can be changed and maintained by calling into the server via 'call' or 'cast'.
Where 'call' is synchronous and waits for a result, 'cast' is asynchronous and responds just with t. For each 'call' and 'cast' handlers must be implemented by subclasses.

GServer runs it's own thread that handles the incoming messages and maintains the state. In that regard message handling should be quick. Long operations should be delegated to elsewhere.

In it's functionality regarding state it is also not unsimilar:

This library also provides an Actor type and an Agent type. Both based on Gserver.

Usage

GServer

Creating a custom gserver

First :use :cl-gserver.

Let's create a simple stack gserver:

First create a new subclass of gserver:

(defclass stack-server (gserver) ())
Synchronous call

Then implement handle-call method which is used to pop or get values since calling a gserver waits for result. Both handle-call and handle-cast provide three parameters. That is the 'server' instance ('self' if you want), the 'message' that was sent, and the 'current-state' of the gserver:

(defmethod handle-call ((server stack-server) message current-state)
  (log:debug "current-state: " current-state)
  (match message
    (:pop
     (cons
      (car current-state)
      (cdr current-state)))
    (:get
     (cons current-state current-state))))

This implements two message handlers using pattern matching with help of trivia library.
You are free to implement the handlers however you like as long as the return conventions are met. An error is raised if no cons is returned, in which case the server responds with (cons :handler-error "<error-message>") to the call.

The convention of handle-call is to always return a cons where the car value is to be returned and the new state value is cdr.

So :pop in the examnple takes the current car of the backing list which will be returned to the caller and cdr of the current state will become the new state.

Asynchronous cast

Now we also want to push values. This will be done by casting to the server.

(defmethod handle-cast ((server stack-server) message current-state)
  (log:debug "current-state: " current-state)
  (match message
    ((cons :push value)
     (let ((new-state (append current-state (list value))))
       (cons new-state new-state)))))

cast is asynchronous and just responds with t. So we can use it to push values to the stack. We still have to return a cons. However, the car of the cons is kind of irrelevant, because it's not returned to the caller. The cdr is important as it will get the new state.

Disclaimer: this is a completely naive implementaion of a stack just using a cons list. Disclaimer2: since cast is asynchronous the push might not yet has updated the gserver state when you do a pop immediately after. So this is not the best example for a cast.

Make instance of stack-server

Now we can make a new server instance with a predefined stack of one entry: 5:

(defparameter *stack-server* (make-instance 'stack-server :state '(5)))

Let's push new values:

(cast *stack-server* (cons :push 4))
(cast *stack-server* (cons :push 3))
(cast *stack-server* (cons :push 2))

When we check the state, we get:

(call *stack-server* :get)
=> returns '(5 4 3 2)

We can also pop the stack:

(call *stack-server* :pop)
=> returns 5
(call *stack-server* :pop)
=> returns 4
(call *stack-server* :pop)
=> returns 3
(call *stack-server* :pop)
=> returns 2

Agent

Usage

An Agent is a specialized GServer. It is meant primarily for maintaining state and comes with some conveniences to do that.

To use an Agent import cl-gserver.agent package.

There is no need to subclass an Agent. An Agent provides three functions to use it.

All three take a lambda.
The lambda for make-agent does not take a parameter. It should return the initial state of the agent.
agent-get and agent-update both take a lambda that must support one parameter. This parameter represents the current state of the agent.

Let's make a simple example:

First create an agent with an initial state of 0.

(defparameter *my-agent* (make-agent (lambda () 0)))

Now update the state several times (agent-update is asynchronous and returns t immediately):

(agent-update *my-agent* (lambda (state) (1+ state)))

Finally get the state:

(agent-get *my-agent* #'identity)

This agent-get just uses the identity function to return the state as is.

So this simple agent represents a counter.

It is important to note that the retrieves state, i.e. with identity should not be modified outside the agent.

Wrapping an agent

While you can use the agent as in the example above it is usually advised to wrap an agent behind a more simple facade that doesn't work with lambdas.

For example could a facade for the counter above look like this:

(defvar *counter-agent* nil)

(defun init-agent (initial-value)
  (setf *counter-agent* (make-agent (lambda () initial-value))))

(defun increment () (agent-update *counter-agent* #'1+))
(defun decrement () (agent-update *counter-agent* #'1-))
(defun counter-value () (agent-get *counter-agent* #'identity))

Alternatively, one can wrap an agent inside a class and provide methods for simplified access to it.

Actor / Simple-Actor

Usage

Actors are another abstraction, or use-case of a GServer (GenServer). However, actors don't exist in Erlang. Actors are pretty much a GServer only that they provider only one method receive to handle both send (which is like cast) and ask (which is like call).
The cons return of receive is also a convention.

To use actors import the cl-gserver.actor package.

You have two choices to implement your actors.

1. Make your own subclass of actor and implement defmethod receive ... (see the actor-test.lisp for details).
2. Use the simple-actor convenience implementation

Let me make a simple ping-pong example here:

(I've added a local package name as act for cl-gserver.actor).

First create a ping actor:

(defparameter *ping* (act:make-actor "ping" 
                                     :state 0 
                                     :receive-fun
                                     (lambda (self msg state)
                                       (trivia:match msg
                                         ((cons :ping sender) (progn
                                                                (log:info "ping from: " sender)
                                                                (sleep 1)
                                                                (when (< state 5)
                                                                  (act:send sender (cons :pong self))
                                                                  (cons nil (1+ state)))))))))

The convenience make-actor function allows you to create a simple actor by specifying the receive-fun inline. Of course you may create a defun for the receive and specify it for :receive-fun like #'my-receive.
The important thing, it must accept three parameters. That is:

The receive-fun also must return a cons equal to the GServer with value for reply and new state.

Now let's create the pong actor:

(defparameter *pong* (act:make-actor "pong" 
                                     :receive-fun
                                     (lambda (self msg state)
                                     (trivia:match msg
                                       ((cons :pong sender) (progn
                                                              (log:info "pong from: " sender)
                                                              (sleep 1)
                                                              (act:send sender (cons :ping self))
                                                              (cons nil nil)))))))

Now we have two actors which can play ping pong.
We trigger it my sending a :ping to the *ping* actor but we also specify the *pong* actor as sender.

(act:send *ping* (cons :ping *pong*))

As can be seen on the *ping* actor definition, it will update it's state by incrementing the received pings. Once they are >= 5 it will stop sending a pong.

Cleaning up resources

A GServer/Actor/Agent can be stopped which will stop the message processing thread.
For GServer and Actor you just send a :stop message and it will respond with :stopped. The :stop message is queued the same way as ordinary messages.

To stop an Agent you need to call agent-stop function. It will also respond with :stopped.

Performance considerations

The test results here were done on an 8 core Xeon system with SBCL.
Number of messages: 8 million with 8 threads each sending 1 million messages.

The message-box is a single Bordeaux-Threads thread which can operate on:

An unbounded queue

The queue used here is the cons-queue of lparallel which has a good performance.

8 million messages could be queezed through this message-box in ~7 seconds.

SBCL:

Evaluation took:
  6.976 seconds of real time
  51.041781 seconds of total run time (50.774304 user, 0.267477 system)
  [ Run times consist of 0.725 seconds GC time, and 50.317 seconds non-GC time. ]
  731.68% CPU
  22,268,009,162 processor cycles
  384,150,656 bytes consed
  
Counter: 8000000
msg/s: 1142857.142857143

The above result is for messages that don't require a feedback. ask, or call messages whcih must deliver the result to the caller are much slower.

Message handling with result delivery:

Evaluation took:
  18.181 seconds of real time
  107.494489 seconds of total run time (30.038678 user, 77.455811 system)
  [ Run times consist of 0.218 seconds GC time, and 107.277 seconds non-GC time. ]
  591.24% CPU
  58,034,749,891 processor cycles
  1,673,953,600 bytes consed
  
Counter: 8000000

This is because some additional locking and waiting must be performed to deliver the result to the caller when it was processed by the message queue.

CCL 1.12 is quite a bit slower altogether than SBCL:

took 25,432,484 microseconds (25.432484 seconds) to run.
      6,055,551 microseconds ( 6.055551 seconds, 23.81%) of which was spent in GC.
During that period, and with 16 available CPU cores,
     33,735,407 microseconds (33.735410 seconds) were spent in user mode
     96,117,573 microseconds (96.117580 seconds) were spent in system mode
 24,208 bytes of memory allocated.
 130,439 minor page faults, 1 major page faults, 0 swaps.
Counter: 8000000

ECL 20.4.24:

real time : 76.989 secs
run time  : 67.377 secs
gc count  : 3 times
consed    : 2952602000 bytes
Counter: 8000000

ABCL 1.6.1:

28.931 seconds real time
87105548 cons cells
Counter: 8000000

Bounded queue

The bounded queue, based on the cl-speedy-queue with some locking around it is slightly faster on my test system. ~0.5s on average. Not much in fact.
The bounded queue on really busy system has some memory resource advantages because it can be limited to value of max entries. It starts back-pressuring when a 90% threshold is reached.

To choose between unbounded and bounded queue you specify :max-queue-size <n> as key argument when making an instance of Gserver, Actor, or Agent. Specify 0 or nil for an unbounded queue and a value > 1 for a bounded queue. However, choose at least 10 entries.

Comparison with Akka

A similar test with Akka on the JVM (Java 8) manages to process 8 million messages in ~4.5 seconds. Which is still a good portion faster than what CL can do.

Alternatives

STMX (transactional memory)

I've also experimented with stmx. This project has a fifo queue ('tfifo') that works with transactional memory.

But timing were by far not as good as with a locking queue. On SBCL, I could only try with 800_000 messages using 8 threads. The value of above, 8 million message couldn't be handled for some reason. But the timing for 800_000 message shows that stmx on SBCL is at least 5 times slower that the locking cons-queue.

However, stmx, or transational memory in general is an alternative option to deal with state in multi-threaded environments.


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

2 Systems

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


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

2.1 cl-gserver

Author

Manfred Bergmann

License

MIT

Description

Erlang inspired GenServer library with Agent for easy access to state.

Version

0.4.0

Dependencies
Source

cl-gserver.asd (file)

Component

src (module)


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

3 Modules

Modules are listed depth-first from the system components tree.


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

3.1 cl-gserver/src

Parent

cl-gserver (system)

Location

src/

Components

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

4 Files

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


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

4.1 Lisp


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

4.1.1 cl-gserver.asd

Location

cl-gserver.asd

Systems

cl-gserver (system)


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

4.1.2 cl-gserver/src/utils.lisp

Parent

src (module)

Location

src/utils.lisp

Packages

cl-gserver.utils

Exported Definitions

mkstr (function)


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

4.1.3 cl-gserver/src/queue.lisp

Dependency

utils.lisp (file)

Parent

src (module)

Location

src/queue.lisp

Packages

cl-gserver.queue

Exported Definitions
Internal Definitions

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

4.1.4 cl-gserver/src/message-box.lisp

Dependency

queue.lisp (file)

Parent

src (module)

Location

src/message-box.lisp

Packages

cl-gserver.messageb

Exported Definitions
Internal Definitions

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

4.1.5 cl-gserver/src/gserver.lisp

Dependency

message-box.lisp (file)

Parent

src (module)

Location

src/gserver.lisp

Packages

cl-gserver

Exported Definitions
Internal Definitions

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

4.1.6 cl-gserver/src/agent.lisp

Dependency

gserver.lisp (file)

Parent

src (module)

Location

src/agent.lisp

Packages

cl-gserver.agent

Exported Definitions

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

4.1.7 cl-gserver/src/actor.lisp

Dependency

agent.lisp (file)

Parent

src (module)

Location

src/actor.lisp

Packages

cl-gserver.actor

Exported Definitions
Internal Definitions

simple-actor (class)


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

5 Packages

Packages are listed by definition order.


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

5.1 cl-gserver.utils

Source

utils.lisp (file)

Nickname

utils

Use List

common-lisp

Used By List
Exported Definitions

mkstr (function)


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

5.2 cl-gserver.queue

Source

queue.lisp (file)

Nickname

queue

Use List

common-lisp

Used By List

cl-gserver.messageb

Exported Definitions
Internal Definitions

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

5.3 cl-gserver.messageb

Source

message-box.lisp (file)

Use List
Exported Definitions
Internal Definitions

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

5.4 cl-gserver

Source

gserver.lisp (file)

Use List
Used By List
Exported Definitions
Internal Definitions

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

5.5 cl-gserver.agent

Source

agent.lisp (file)

Use List
Exported Definitions

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

5.6 cl-gserver.actor

Source

actor.lisp (file)

Nickname

act

Use List
Exported Definitions
Internal Definitions

simple-actor (class)


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

6 Definitions

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


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

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Macros

Macro: with-submit-handler (MSGBOX MESSAGE WITHREPLY-P) &rest BODY

Macro to let the caller specify a message handler function.

Package

cl-gserver.messageb

Source

message-box.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.2 Functions

Function: agent-get AGENT GET-FUN

Gets the current state of the ‘agent’.
‘get-fun’ must accept one parameter. That is the current-state of the ‘agent’. To return the current state ‘get-fun’ may be just the ‘identity’ function. See ‘agent-test’ for examples.

Package

cl-gserver.agent

Source

agent.lisp (file)

Function: agent-stop AGENT

Stops the message handling of the agent.

Package

cl-gserver.agent

Source

agent.lisp (file)

Function: agent-update AGENT UPDATE-FUN

Updates the ‘agent’ state.
‘update-fun’ must accept one parameter. That is the current state of the ‘agent’. The return value of ‘update-fun’ will be taken as the new state of the ‘agent’.

Package

cl-gserver.agent

Source

agent.lisp (file)

Function: ask ACTOR MESSAGE

Sends a message to the ‘actor’. ‘ask’ is synchronous and waits for a result.

Package

cl-gserver.actor

Source

actor.lisp (file)

Function: call GSERVER MESSAGE

Send a message to a gserver instance and wait for a result. The result can be of different types.
Success result: <returned-state>
qUnhandled result: :unhandled
Error result: (cons :handler-error <error-description-as-string>)

Package

cl-gserver

Source

gserver.lisp (file)

Function: cast GSERVER MESSAGE

Sends a message to a gserver asynchronously. There is no result.

Package

cl-gserver

Source

gserver.lisp (file)

Function: init-dispatcher-threadpool SIZE
Package

cl-gserver

Source

gserver.lisp (file)

Function: make-actor NAME &key STATE RECEIVE-FUN AFTER-INIT-FUN

Makes a new ‘simple-actor’ which allows you to specify a name with ‘:state’, ‘:receive-fun’ and ‘:after-init-fun’.

Package

cl-gserver.actor

Source

actor.lisp (file)

Function: make-agent STATE-FUN

Makes a new ‘agent’ instance.
‘state-fun’ is a function that takes no parameter and provides the initial state of the ‘agent’ as return value.

Package

cl-gserver.agent

Source

agent.lisp (file)

Function: mkstr &rest ARGS

Converts all parameters to string and concatenates them.

Package

cl-gserver.utils

Source

utils.lisp (file)

Function: send ACTOR MESSAGE

Sends a message to the ‘actor’. ‘send’ is asynchronous.

Package

cl-gserver.actor

Source

actor.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.3 Generic functions

Generic Function: after-init SERVER STATE

Generic function definition that you may call from ‘initialize-instance’.

Package

cl-gserver

Source

gserver.lisp (file)

Methods
Method: after-init (SELF simple-actor) STATE
Source

actor.lisp (file)

Generic Function: handle-call GSERVER MESSAGE CURRENT-STATE

Handles calls to the server. Must be implemented by subclasses.
The convention here is to return a ‘cons’ with values to be returned to caller as ‘car’, and the new state as ‘cdr’. ‘handle-call’ is executed in the default message dispatcher thread.

Package

cl-gserver

Source

gserver.lisp (file)

Methods
Method: handle-call (SELF actor) MESSAGE CURRENT-STATE
Source

actor.lisp (file)

Method: handle-call (SELF agent) MESSAGE CURRENT-STATE
Source

agent.lisp (file)

Generic Function: handle-cast GSERVER MESSAGE CURRENT-STATE

Handles casts to the server. Must be implemented by subclasses.
Same convention as for ’handle-call’ except that no return is sent to the caller. This function returns immediately.

Package

cl-gserver

Source

gserver.lisp (file)

Methods
Method: handle-cast (SELF actor) MESSAGE CURRENT-STATE
Source

actor.lisp (file)

Method: handle-cast (SELF agent) MESSAGE CURRENT-STATE
Source

agent.lisp (file)

Generic Function: name OBJECT
Generic Function: (setf name) NEW-VALUE OBJECT
Package

cl-gserver

Methods
Method: name (GSERVER gserver)
Method: (setf name) NEW-VALUE (GSERVER gserver)

The name of the gserver. If no name is specified a default one is applied.

Source

gserver.lisp (file)

Generic Function: popq QUEUE-BASE

Pops the first element. Blocks until an element arrives.

Package

cl-gserver.queue

Source

queue.lisp (file)

Methods
Method: popq (SELF queue-bounded)
Method: popq (SELF queue-unbounded)
Generic Function: pushq QUEUE-BASE ELEMENT

Pushes an element to the queue.

Package

cl-gserver.queue

Source

queue.lisp (file)

Methods
Method: pushq (SELF queue-bounded) ELEMENT
Method: pushq (SELF queue-unbounded) ELEMENT
Generic Function: receive ACTOR MESSAGE CURRENT-STATE

The ‘receive’ method handles all messages to an ‘actor’ being it ‘send’ or ‘ask’. But the convention persists that the result of ‘receive’ must be a ‘cons’ where ‘car’ is to be returned to the caller (for ‘ask’) and ‘cdr’ will update the state.

Package

cl-gserver.actor

Source

actor.lisp (file)

Methods
Method: receive (SELF simple-actor) MESSAGE CURRENT-STATE
Generic Function: stop MESSAGE-BOX-BASE

Stops the message processing.

Package

cl-gserver.messageb

Source

message-box.lisp (file)

Methods
Method: stop (SELF message-box-lsr)
Method: stop (SELF message-box-bt)
Method: stop (SELF message-box-base)
Generic Function: submit MESSAGE-BOX-BASE MESSAGE WITHREPLY-P HANDLER-FUN

Submit a message to the mailbox to be queued and handled.

Package

cl-gserver.messageb

Source

message-box.lisp (file)

Methods
Method: submit (SELF message-box-lsr) MESSAGE WITHREPLY-P HANDLER-FUN
Method: submit (SELF message-box-bt) MESSAGE WITHREPLY-P HANDLER-FUN

Alternatively use ‘with-submit-handler’ from your code to handle the message after it was ’popped’ from the queue. The ‘handler-fun’ argument here will be ‘funcall’ed when the message was ’popped’.


Previous: , Up: Exported definitions   [Contents][Index]

6.1.4 Classes

Class: actor ()

Specialized ‘gserver’ class called ‘actor’.
There is a different terminology behind ‘actor’.
I.e. There is only one ‘receive’ function.
And there is asynchronous ‘send’ and synchronous ‘ask’.
So there is not much difference to a ‘gserver’.
It only uses one method ‘receive’. However both ‘handle-call’ and ‘handle-cast’ of ‘gserver’
end up in ‘receive’.

To stop an actors message processing in order to cleanup resouces you should send (either ‘send’ or ‘ask’) the ‘:stop’ message. It will respond with ‘:stopped’.

Package

cl-gserver.actor

Source

actor.lisp (file)

Direct superclasses

gserver (class)

Direct subclasses

simple-actor (class)

Direct methods
Class: agent ()

Specialized ‘gserver’ class called ‘agent’.
It is meant primarily to encapsulate state.
To access state it provides ‘agent-get’ and ‘agent-update’ to update state.

Package

cl-gserver.agent

Source

agent.lisp (file)

Direct superclasses

gserver (class)

Direct methods
Class: gserver ()

GServer is an Erlang inspired GenServer.
It is meant to encapsulate state, but also to execute async operations.
State can be changed by calling into the server via ‘call’ or ‘cast’.
Where ‘call’ is waiting for a result and ‘cast’ does not.
For each ‘call’ and ‘cast’ handlers must be implemented by subclasses.

A GServer runs it’s own thread, actually a lparallel message-kernel with one worker,
to handle the messages which will eventually update the state.

To stop a Gserver message handling and thread pool you can send the ‘:stop’ message either via ‘call’ (which will respond with ‘:stopped’) or ‘cast’. This is to cleanup thread resources when the Gserver is not needed anymore.

Package

cl-gserver

Source

gserver.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses
Direct methods
  • initialize-instance (method)
  • name (method)
  • name (method)
Direct slots
Slot: name

The name of the gserver. If no name is specified a default one is applied.

Initargs

:name

Initform

(cl-gserver.utils:mkstr "server-" (random 100000))

Readers

name (generic function)

Writers

(setf name) (generic function)

Slot: state

The encapsulated state.

Initargs

:state

Slot: internal-state

The internal state of the server.

Initargs

:internal-state

Initform

(cl-gserver::make-gserver-state)

Slot: max-queue-size

0 or nil for unbounded queue. > 0 for bounded queue. Don’t choose < 10.

Initargs

:max-queue-size

Slot: msgbox
Class: message-box-bt ()

Bordeaux-Threads based message-box with a single thread operating on a message queue. This is used as default.

Package

cl-gserver.messageb

Source

message-box.lisp (file)

Direct superclasses

message-box-base (class)

Direct methods
  • stop (method)
  • submit (method)
  • initialize-instance (method)
Direct slots
Slot: queue-thread

The thread that pops queue items.

Slot: queue

Which type of queue will be used depends on the ‘max-queue-size’ setting.

Slot: should-run

Flag that indicates whether the message processing should commence.

Initform

t

Class: message-box-lsr ()
Package

cl-gserver.messageb

Source

message-box.lisp (file)

Direct superclasses

message-box-base (class)

Direct methods
  • stop (method)
  • submit (method)
  • initialize-instance (method)
Direct slots
Slot: message-kernel

The message-kernel with 1 worker for handling the messages.

Slot: message-channel

The message-channel for the message-kernel. Since we only have 1 worker here it is safe to make an instance channel regarding FIFO.

Class: queue-bounded ()

Bounded queue.

Package

cl-gserver.queue

Source

queue.lisp (file)

Direct superclasses

queue-base (class)

Direct methods
  • popq (method)
  • pushq (method)
  • initialize-instance (method)
Direct slots
Slot: queue
Slot: lock
Initform

(bordeaux-threads:make-lock)

Slot: cvar
Initform

(bordeaux-threads:make-condition-variable)

Slot: max-items
Initargs

:max-items

Initform

1000

Slot: yield-threshold
Class: queue-unbounded ()

Unbounded queue based on lparallels cons-queue.

Package

cl-gserver.queue

Source

queue.lisp (file)

Direct superclasses

queue-base (class)

Direct methods
Direct slots
Slot: queue
Initform

(lparallel.cons-queue:make-cons-queue)


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

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Functions

Function: after-submit-message GSERVER MESSAGE RESPONSE
Package

cl-gserver

Source

gserver.lisp (file)

Function: backpressure-if-necessary-on QUEUE YIELD-THRESHOLD
Package

cl-gserver.queue

Source

queue.lisp (file)

Function: copy-gserver-state INSTANCE
Package

cl-gserver

Source

gserver.lisp (file)

Function: copy-message-item INSTANCE
Package

cl-gserver.messageb

Source

message-box.lisp (file)

Function: dequeue/no-wait QUEUE
Package

cl-gserver.queue

Source

queue.lisp (file)

Function: dequeue/wait QUEUE CVAR LOCK
Package

cl-gserver.queue

Source

queue.lisp (file)

Function: get-queue-count QUEUE
Package

cl-gserver.queue

Source

queue.lisp (file)

Function: gserver-state-p OBJECT
Package

cl-gserver

Source

gserver.lisp (file)

Function: gserver-state-running INSTANCE
Function: (setf gserver-state-running) VALUE INSTANCE
Package

cl-gserver

Source

gserver.lisp (file)

Function: handle-message GSERVER MESSAGE WITHREPLY-P

This function is called from message-box as a callback.

Package

cl-gserver

Source

gserver.lisp (file)

Function: handle-message-internal MSG

A ‘:stop’ message will response with ‘:stopping’ and the user handlers are not called. Otherwise the result is ‘nil’ to resume user message handling.

Package

cl-gserver

Source

gserver.lisp (file)

Function: handle-message-user GSERVER MESSAGE WITHREPLY-P

This will call the method ’handle-call’ with the message.

Package

cl-gserver

Source

gserver.lisp (file)

Function: make-gserver-state &key (RUNNING RUNNING)
Package

cl-gserver

Source

gserver.lisp (file)

Function: make-message-item &key (MESSAGE MESSAGE) (WITHREPLY-P WITHREPLY-P) (WITHREPLY-LOCK WITHREPLY-LOCK) (WITHREPLY-CVAR WITHREPLY-CVAR) (HANDLER-FUN HANDLER-FUN)
Package

cl-gserver.messageb

Source

message-box.lisp (file)

Function: message-item-handler-fun INSTANCE
Function: (setf message-item-handler-fun) VALUE INSTANCE
Package

cl-gserver.messageb

Source

message-box.lisp (file)

Function: message-item-message INSTANCE
Function: (setf message-item-message) VALUE INSTANCE
Package

cl-gserver.messageb

Source

message-box.lisp (file)

Function: message-item-p OBJECT
Package

cl-gserver.messageb

Source

message-box.lisp (file)

Function: message-item-withreply-cvar INSTANCE
Function: (setf message-item-withreply-cvar) VALUE INSTANCE
Package

cl-gserver.messageb

Source

message-box.lisp (file)

Function: message-item-withreply-lock INSTANCE
Function: (setf message-item-withreply-lock) VALUE INSTANCE
Package

cl-gserver.messageb

Source

message-box.lisp (file)

Function: message-item-withreply-p INSTANCE
Function: (setf message-item-withreply-p) VALUE INSTANCE
Package

cl-gserver.messageb

Source

message-box.lisp (file)

Function: message-processing-loop MSGBOX

The message processing loop.

Package

cl-gserver.messageb

Source

message-box.lisp (file)

Function: pop-queue-and-process MSGBOX

This blocks until a new queue item arrived.

Package

cl-gserver.messageb

Source

message-box.lisp (file)

Function: process-handler-result HANDLE-RESULT GSERVER
Package

cl-gserver

Source

gserver.lisp (file)

Function: process-not-handled ()
Package

cl-gserver

Source

gserver.lisp (file)

Function: process-queue-item ITEM
Package

cl-gserver.messageb

Source

message-box.lisp (file)

Function: reply-value CONS-RESULT
Package

cl-gserver

Source

gserver.lisp (file)

Function: stop-server GSERVER
Package

cl-gserver

Source

gserver.lisp (file)

Function: submit-message GSERVER MESSAGE WITHREPLY-P
Package

cl-gserver

Source

gserver.lisp (file)

Function: submit/no-reply QUEUE MESSAGE HANDLER-FUN
Package

cl-gserver.messageb

Source

message-box.lisp (file)

Function: submit/reply QUEUE MESSAGE HANDLER-FUN
Package

cl-gserver.messageb

Source

message-box.lisp (file)

Function: update-state GSERVER CONS-RESULT
Package

cl-gserver

Source

gserver.lisp (file)

Function: wait-condition COND-FUN &optional SLEEP-TIME MAX-TIME
Package

cl-gserver.messageb

Source

message-box.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Structures

Structure: gserver-state ()
Package

cl-gserver

Source

gserver.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: running
Type

boolean

Initform

t

Readers

gserver-state-running (function)

Writers

(setf gserver-state-running) (function)

Structure: message-item ()
Package

cl-gserver.messageb

Source

message-box.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: message
Readers

message-item-message (function)

Writers

(setf message-item-message) (function)

Slot: withreply-p
Type

boolean

Readers

message-item-withreply-p (function)

Writers

(setf message-item-withreply-p) (function)

Slot: withreply-lock
Readers

message-item-withreply-lock (function)

Writers

(setf message-item-withreply-lock) (function)

Slot: withreply-cvar
Readers

message-item-withreply-cvar (function)

Writers

(setf message-item-withreply-cvar) (function)

Slot: handler-fun
Type

function

Readers

message-item-handler-fun (function)

Writers

(setf message-item-handler-fun) (function)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.3 Classes

Class: message-box-base ()
Package

cl-gserver.messageb

Source

message-box.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses
Direct methods

stop (method)

Direct slots
Slot: name
Initform

(cl-gserver.utils:mkstr "messagebox-" (random 1000000))

Slot: processed-messages
Initform

0

Slot: max-queue-size

0 or nil will make an unbounded queue.
A value > 0 will make a bounded queue.
Don’t make it too small. A queue size of 1000 might be a good choice.

Initargs

:max-queue-size

Initform

0

Class: queue-base ()

The base queue.

Package

cl-gserver.queue

Source

queue.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses
Direct slots
Slot: queue
Class: simple-actor ()

A simplified actor that can be created with just ‘make-actor’.

Package

cl-gserver.actor

Source

actor.lisp (file)

Direct superclasses

actor (class)

Direct methods
Direct slots
Slot: receive-fun

The receive function specified as slot.

Initargs

:receive-fun

Slot: after-init-fun

Code to be called after actor start.

Initargs

:after-init-fun


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   C   F   L   M  
Index Entry  Section

C
cl-gserver.asd: The cl-gserver․asd file
cl-gserver/src: The cl-gserver/src module
cl-gserver/src/actor.lisp: The cl-gserver/src/actor․lisp file
cl-gserver/src/agent.lisp: The cl-gserver/src/agent․lisp file
cl-gserver/src/gserver.lisp: The cl-gserver/src/gserver․lisp file
cl-gserver/src/message-box.lisp: The cl-gserver/src/message-box․lisp file
cl-gserver/src/queue.lisp: The cl-gserver/src/queue․lisp file
cl-gserver/src/utils.lisp: The cl-gserver/src/utils․lisp file

F
File, Lisp, cl-gserver.asd: The cl-gserver․asd file
File, Lisp, cl-gserver/src/actor.lisp: The cl-gserver/src/actor․lisp file
File, Lisp, cl-gserver/src/agent.lisp: The cl-gserver/src/agent․lisp file
File, Lisp, cl-gserver/src/gserver.lisp: The cl-gserver/src/gserver․lisp file
File, Lisp, cl-gserver/src/message-box.lisp: The cl-gserver/src/message-box․lisp file
File, Lisp, cl-gserver/src/queue.lisp: The cl-gserver/src/queue․lisp file
File, Lisp, cl-gserver/src/utils.lisp: The cl-gserver/src/utils․lisp file

L
Lisp File, cl-gserver.asd: The cl-gserver․asd file
Lisp File, cl-gserver/src/actor.lisp: The cl-gserver/src/actor․lisp file
Lisp File, cl-gserver/src/agent.lisp: The cl-gserver/src/agent․lisp file
Lisp File, cl-gserver/src/gserver.lisp: The cl-gserver/src/gserver․lisp file
Lisp File, cl-gserver/src/message-box.lisp: The cl-gserver/src/message-box․lisp file
Lisp File, cl-gserver/src/queue.lisp: The cl-gserver/src/queue․lisp file
Lisp File, cl-gserver/src/utils.lisp: The cl-gserver/src/utils․lisp file

M
Module, cl-gserver/src: The cl-gserver/src module

Jump to:   C   F   L   M  

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

A.2 Functions

Jump to:   (  
A   B   C   D   F   G   H   I   M   N   P   R   S   U   W  
Index Entry  Section

(
(setf gserver-state-running): Internal functions
(setf message-item-handler-fun): Internal functions
(setf message-item-message): Internal functions
(setf message-item-withreply-cvar): Internal functions
(setf message-item-withreply-lock): Internal functions
(setf message-item-withreply-p): Internal functions
(setf name): Exported generic functions
(setf name): Exported generic functions

A
after-init: Exported generic functions
after-init: Exported generic functions
after-submit-message: Internal functions
agent-get: Exported functions
agent-stop: Exported functions
agent-update: Exported functions
ask: Exported functions

B
backpressure-if-necessary-on: Internal functions

C
call: Exported functions
cast: Exported functions
copy-gserver-state: Internal functions
copy-message-item: Internal functions

D
dequeue/no-wait: Internal functions
dequeue/wait: Internal functions

F
Function, (setf gserver-state-running): Internal functions
Function, (setf message-item-handler-fun): Internal functions
Function, (setf message-item-message): Internal functions
Function, (setf message-item-withreply-cvar): Internal functions
Function, (setf message-item-withreply-lock): Internal functions
Function, (setf message-item-withreply-p): Internal functions
Function, after-submit-message: Internal functions
Function, agent-get: Exported functions
Function, agent-stop: Exported functions
Function, agent-update: Exported functions
Function, ask: Exported functions
Function, backpressure-if-necessary-on: Internal functions
Function, call: Exported functions
Function, cast: Exported functions
Function, copy-gserver-state: Internal functions
Function, copy-message-item: Internal functions
Function, dequeue/no-wait: Internal functions
Function, dequeue/wait: Internal functions
Function, get-queue-count: Internal functions
Function, gserver-state-p: Internal functions
Function, gserver-state-running: Internal functions
Function, handle-message: Internal functions
Function, handle-message-internal: Internal functions
Function, handle-message-user: Internal functions
Function, init-dispatcher-threadpool: Exported functions
Function, make-actor: Exported functions
Function, make-agent: Exported functions
Function, make-gserver-state: Internal functions
Function, make-message-item: Internal functions
Function, message-item-handler-fun: Internal functions
Function, message-item-message: Internal functions
Function, message-item-p: Internal functions
Function, message-item-withreply-cvar: Internal functions
Function, message-item-withreply-lock: Internal functions
Function, message-item-withreply-p: Internal functions
Function, message-processing-loop: Internal functions
Function, mkstr: Exported functions
Function, pop-queue-and-process: Internal functions
Function, process-handler-result: Internal functions
Function, process-not-handled: Internal functions
Function, process-queue-item: Internal functions
Function, reply-value: Internal functions
Function, send: Exported functions
Function, stop-server: Internal functions
Function, submit-message: Internal functions
Function, submit/no-reply: Internal functions
Function, submit/reply: Internal functions
Function, update-state: Internal functions
Function, wait-condition: Internal functions

G
Generic Function, (setf name): Exported generic functions
Generic Function, after-init: Exported generic functions
Generic Function, handle-call: Exported generic functions
Generic Function, handle-cast: Exported generic functions
Generic Function, name: Exported generic functions
Generic Function, popq: Exported generic functions
Generic Function, pushq: Exported generic functions
Generic Function, receive: Exported generic functions
Generic Function, stop: Exported generic functions
Generic Function, submit: Exported generic functions
get-queue-count: Internal functions
gserver-state-p: Internal functions
gserver-state-running: Internal functions

H
handle-call: Exported generic functions
handle-call: Exported generic functions
handle-call: Exported generic functions
handle-cast: Exported generic functions
handle-cast: Exported generic functions
handle-cast: Exported generic functions
handle-message: Internal functions
handle-message-internal: Internal functions
handle-message-user: Internal functions

I
init-dispatcher-threadpool: Exported functions

M
Macro, with-submit-handler: Exported macros
make-actor: Exported functions
make-agent: Exported functions
make-gserver-state: Internal functions
make-message-item: Internal functions
message-item-handler-fun: Internal functions
message-item-message: Internal functions
message-item-p: Internal functions
message-item-withreply-cvar: Internal functions
message-item-withreply-lock: Internal functions
message-item-withreply-p: Internal functions
message-processing-loop: Internal functions
Method, (setf name): Exported generic functions
Method, after-init: Exported generic functions
Method, handle-call: Exported generic functions
Method, handle-call: Exported generic functions
Method, handle-cast: Exported generic functions
Method, handle-cast: Exported generic functions
Method, name: Exported generic functions
Method, popq: Exported generic functions
Method, popq: Exported generic functions
Method, pushq: Exported generic functions
Method, pushq: Exported generic functions
Method, receive: Exported generic functions
Method, stop: Exported generic functions
Method, stop: Exported generic functions
Method, stop: Exported generic functions
Method, submit: Exported generic functions
Method, submit: Exported generic functions
mkstr: Exported functions

N
name: Exported generic functions
name: Exported generic functions

P
pop-queue-and-process: Internal functions
popq: Exported generic functions
popq: Exported generic functions
popq: Exported generic functions
process-handler-result: Internal functions
process-not-handled: Internal functions
process-queue-item: Internal functions
pushq: Exported generic functions
pushq: Exported generic functions
pushq: Exported generic functions

R
receive: Exported generic functions
receive: Exported generic functions
reply-value: Internal functions

S
send: Exported functions
stop: Exported generic functions
stop: Exported generic functions
stop: Exported generic functions
stop: Exported generic functions
stop-server: Internal functions
submit: Exported generic functions
submit: Exported generic functions
submit: Exported generic functions
submit-message: Internal functions
submit/no-reply: Internal functions
submit/reply: Internal functions

U
update-state: Internal functions

W
wait-condition: Internal functions
with-submit-handler: Exported macros

Jump to:   (  
A   B   C   D   F   G   H   I   M   N   P   R   S   U   W  

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

A.3 Variables

Jump to:   A   C   H   I   L   M   N   P   Q   R   S   W   Y  
Index Entry  Section

A
after-init-fun: Internal classes

C
cvar: Exported classes

H
handler-fun: Internal structures

I
internal-state: Exported classes

L
lock: Exported classes

M
max-items: Exported classes
max-queue-size: Exported classes
max-queue-size: Internal classes
message: Internal structures
message-channel: Exported classes
message-kernel: Exported classes
msgbox: Exported classes

N
name: Exported classes
name: Internal classes

P
processed-messages: Internal classes

Q
queue: Exported classes
queue: Exported classes
queue: Exported classes
queue: Internal classes
queue-thread: Exported classes

R
receive-fun: Internal classes
running: Internal structures

S
should-run: Exported classes
Slot, after-init-fun: Internal classes
Slot, cvar: Exported classes
Slot, handler-fun: Internal structures
Slot, internal-state: Exported classes
Slot, lock: Exported classes
Slot, max-items: Exported classes
Slot, max-queue-size: Exported classes
Slot, max-queue-size: Internal classes
Slot, message: Internal structures
Slot, message-channel: Exported classes
Slot, message-kernel: Exported classes
Slot, msgbox: Exported classes
Slot, name: Exported classes
Slot, name: Internal classes
Slot, processed-messages: Internal classes
Slot, queue: Exported classes
Slot, queue: Exported classes
Slot, queue: Exported classes
Slot, queue: Internal classes
Slot, queue-thread: Exported classes
Slot, receive-fun: Internal classes
Slot, running: Internal structures
Slot, should-run: Exported classes
Slot, state: Exported classes
Slot, withreply-cvar: Internal structures
Slot, withreply-lock: Internal structures
Slot, withreply-p: Internal structures
Slot, yield-threshold: Exported classes
state: Exported classes

W
withreply-cvar: Internal structures
withreply-lock: Internal structures
withreply-p: Internal structures

Y
yield-threshold: Exported classes

Jump to:   A   C   H   I   L   M   N   P   Q   R   S   W   Y  

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

A.4 Data types

Jump to:   A   C   G   M   P   Q   S  
Index Entry  Section

A
actor: Exported classes
agent: Exported classes

C
cl-gserver: The cl-gserver system
cl-gserver: The cl-gserver package
cl-gserver.actor: The cl-gserver․actor package
cl-gserver.agent: The cl-gserver․agent package
cl-gserver.messageb: The cl-gserver․messageb package
cl-gserver.queue: The cl-gserver․queue package
cl-gserver.utils: The cl-gserver․utils package
Class, actor: Exported classes
Class, agent: Exported classes
Class, gserver: Exported classes
Class, message-box-base: Internal classes
Class, message-box-bt: Exported classes
Class, message-box-lsr: Exported classes
Class, queue-base: Internal classes
Class, queue-bounded: Exported classes
Class, queue-unbounded: Exported classes
Class, simple-actor: Internal classes

G
gserver: Exported classes
gserver-state: Internal structures

M
message-box-base: Internal classes
message-box-bt: Exported classes
message-box-lsr: Exported classes
message-item: Internal structures

P
Package, cl-gserver: The cl-gserver package
Package, cl-gserver.actor: The cl-gserver․actor package
Package, cl-gserver.agent: The cl-gserver․agent package
Package, cl-gserver.messageb: The cl-gserver․messageb package
Package, cl-gserver.queue: The cl-gserver․queue package
Package, cl-gserver.utils: The cl-gserver․utils package

Q
queue-base: Internal classes
queue-bounded: Exported classes
queue-unbounded: Exported classes

S
simple-actor: Internal classes
Structure, gserver-state: Internal structures
Structure, message-item: Internal structures
System, cl-gserver: The cl-gserver system

Jump to:   A   C   G   M   P   Q   S