The trivial-channels Reference Manual

Table of Contents

The trivial-channels Reference Manual

This is the trivial-channels Reference Manual, version 1.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Mar 25 19:22:18 2020 GMT+0.

1 Introduction

trivial-channels

This is a very, very trivial implementation of channels (and a queue). I find myself using it in a few places where very trivial message passing is needed and a more complex, robust solution would be overkill.

(let ((channel (make-channel)))
  (sendmsg channel 'anything)
  (recvmsg channel)) ;; => ANYTHING

API

• (make-channel): Make a channel
• (sendmsg CHANNEL OBJECT): Send OBJECT on CHANNEL
• (recvmsg CHANNEL &optional TIMEOUT): Receive on CHANNEL, optionally timing out after TIMEOUT seconds
• (getmsg CHANNEL): Get a message if available, or NIL
• (hasmsg CHANNEL): Whether the channel has a message. No guarantee it will still have one after the call, if there are multiple receivers sharing a channel.

Notably, recvmsg supports a timeout. These functions properly lock and it's safe to share a channel between threads (that being the entire purpose).

Usage

While trivial-channels should be simple enough you can adapt it to many usage patterns, for simple bi-directional message passing I have found it easiest to simply pass a message with a return-channel included:

;;; Sender:
(defvar *global-listener* (make-channel))
(defvar *done* nil)

(let* ((return-channel (make-channel))
       (msg (cons 'value return-channel)))
  (sendmsg *global-listener* msg)
  (recvmsg return-channel))

;;; Meanwhile, in another thread:
(loop until *done* do
  (let ((msg (recvmsg *global-listener*)))
    (let ((value (car msg))
          (channel (cdr msg)))
      ;; insert useful things here
      (sendmsg channel ...))))

Of course, you needn't create a new return channel every time, either, if you are worried about consing, but this is an easy way to pass functions to a specific thread, implement actors, etc.

Queues

The queue used to implement this is also available via the package :trivial-channels.queue, since it's sometimes handy to have a trivial queue, too.

Queues do not lock.

Queues are implemented with conses.

• (make-queue): Make a queue
• (queue-head Q): Head of the queue
• (queue-tail Q): Tail of the queue
• (queue-add-cons Q CONS): CONS becomes the tail of the queue; its CDR may be destructively modified
• (queue-add Q ITEM): Add ITEM to the tail of the queue
• (queue-push Q ITEM): Push ITEM onto the front of the queue
• (queue-pop Q): Pop and return and item from the queue, or NIL
• (queue-pop-cons Q): Pop and return the cons from the queue, or NIL
• (queue-has-item-p Q): If there are items in the queue, or NIL
• (queue-peek Q): The front item in the queue, or NIL
• (queue-pop-to Q1 Q2): Pop an item from Q1 and add it to Q2 without consing
• (queue-prepend-to Q1 Q2): Remove all items from Q1 and prepend them to Q2 without consing; no value returned

All add or remove type operations return the item (or cons) being handled, unless otherwise noted.

2 Systems

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

2.1 trivial-channels

Author

Ryan Pavlik

License

BSD-2-Clause

Description

Really simple channels and queue

Version

1.0

Dependencies

• bordeaux-threads
• trivial-timeout

Source

trivial-channels.asd (file)

Components

• package.lisp (file)
• trivial-channels.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 trivial-channels.asd

Location

trivial-channels.asd

Systems

trivial-channels (system)

Packages

trivial-channels.asdf

3.1.2 trivial-channels/package.lisp

Parent

trivial-channels (system)

Location

package.lisp

Packages

• trivial-channels.queue
• trivial-channels

3.1.3 trivial-channels/trivial-channels.lisp

Dependency

package.lisp (file)

Parent

trivial-channels (system)

Location

trivial-channels.lisp

Exported Definitions

• channel (structure)
• getmsg (function)
• hasmsg (function)
• make-channel (function)
• make-queue (function)
• queue (structure)
• queue-add (function)
• queue-add-cons (function)
• queue-has-item-p (function)
• queue-head (function)
• (setf queue-head) (function)
• queue-peek (function)
• queue-pop (function)
• queue-pop-cons (function)
• queue-pop-to (function)
• queue-prepend-to (function)
• queue-push (function)
• queue-tail (function)
• (setf queue-tail) (function)
• recvmsg (function)
• sendmsg (function)

Internal Definitions

• channel-p (function)
• channel-q-condition (function)
• (setf channel-q-condition) (function)
• channel-q-mutex (function)
• (setf channel-q-mutex) (function)
• channel-queue (function)
• (setf channel-queue) (function)
• copy-channel (function)
• copy-queue (function)
• queue-p (function)
• wait-with-timeout (function)

4 Packages

Packages are listed by definition order.

4.1 trivial-channels.asdf

Source

trivial-channels.asd

Use List

• asdf/interface
• common-lisp

4.2 trivial-channels.queue

Source

package.lisp (file)

Use List

common-lisp

Used By List

trivial-channels

Exported Definitions

• make-queue (function)
• queue (structure)
• queue-add (function)
• queue-add-cons (function)
• queue-has-item-p (function)
• queue-head (function)
• (setf queue-head) (function)
• queue-peek (function)
• queue-pop (function)
• queue-pop-cons (function)
• queue-pop-to (function)
• queue-prepend-to (function)
• queue-push (function)
• queue-tail (function)
• (setf queue-tail) (function)

Internal Definitions

• copy-queue (function)
• queue-p (function)

4.3 trivial-channels

Source

package.lisp (file)

Use List

• trivial-channels.queue
• common-lisp

Exported Definitions

• channel (structure)
• getmsg (function)
• hasmsg (function)
• make-channel (function)
• recvmsg (function)
• sendmsg (function)

Internal Definitions

• channel-p (function)
• channel-q-condition (function)
• (setf channel-q-condition) (function)
• channel-q-mutex (function)
• (setf channel-q-mutex) (function)
• channel-queue (function)
• (setf channel-queue) (function)
• copy-channel (function)
• wait-with-timeout (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Functions

Function: getmsg CHANNEL

Package

trivial-channels

Source

trivial-channels.lisp (file)

Function: hasmsg CHANNEL

Package

trivial-channels

Source

trivial-channels.lisp (file)

Function: make-channel &key (QUEUE QUEUE) (Q-CONDITION Q-CONDITION) (Q-MUTEX Q-MUTEX)

Package

trivial-channels

Source

trivial-channels.lisp (file)

Function: make-queue &key (HEAD HEAD) (TAIL TAIL)

Package

trivial-channels.queue

Source

trivial-channels.lisp (file)

Function: queue-add Q ITEM

Package

trivial-channels.queue

Source

trivial-channels.lisp (file)

Function: queue-add-cons Q CONS

Package

trivial-channels.queue

Source

trivial-channels.lisp (file)

Function: queue-has-item-p Q

Package

trivial-channels.queue

Source

trivial-channels.lisp (file)

Function: queue-head INSTANCE

Function: (setf queue-head) VALUE INSTANCE

Package

trivial-channels.queue

Source

trivial-channels.lisp (file)

Function: queue-peek Q

Peek at the head of the queue.

Package

trivial-channels.queue

Source

trivial-channels.lisp (file)

Function: queue-pop Q

Package

trivial-channels.queue

Source

trivial-channels.lisp (file)

Function: queue-pop-cons Q

Package

trivial-channels.queue

Source

trivial-channels.lisp (file)

Function: queue-pop-to Q1 Q2

Pop from ‘Q1‘, adding to ‘Q2‘, without consing.

Package

trivial-channels.queue

Source

trivial-channels.lisp (file)

Function: queue-prepend-to Q1 Q2

Prepend all items in ‘Q1‘ to ‘Q2‘, removing them from ‘Q1‘

Package

trivial-channels.queue

Source

trivial-channels.lisp (file)

Function: queue-push Q ITEM

Package

trivial-channels.queue

Source

trivial-channels.lisp (file)

Function: queue-tail INSTANCE

Function: (setf queue-tail) VALUE INSTANCE

Package

trivial-channels.queue

Source

trivial-channels.lisp (file)

Function: recvmsg CHANNEL &optional TIMEOUT

Package

trivial-channels

Source

trivial-channels.lisp (file)

Function: sendmsg CHANNEL MSG

Package

trivial-channels

Source

trivial-channels.lisp (file)

5.1.2 Structures

Structure: channel ()

Package

trivial-channels

Source

trivial-channels.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: queue

Type

trivial-channels.queue:queue

Initform

(trivial-channels.queue:make-queue)

Readers

channel-queue (function)

Writers

(setf channel-queue) (function)

Slot: q-condition

Initform

(bordeaux-threads:make-condition-variable)

Readers

channel-q-condition (function)

Writers

(setf channel-q-condition) (function)

Slot: q-mutex

Initform

(bordeaux-threads:make-lock)

Readers

channel-q-mutex (function)

Writers

(setf channel-q-mutex) (function)

Structure: queue ()

Package

trivial-channels.queue

Source

trivial-channels.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: head

Readers

queue-head (function)

Writers

(setf queue-head) (function)

Slot: tail

Readers

queue-tail (function)

Writers

(setf queue-tail) (function)

5.2 Internal definitions

5.2.1 Functions

Function: channel-p OBJECT

Package

trivial-channels

Source

trivial-channels.lisp (file)

Function: channel-q-condition INSTANCE

Function: (setf channel-q-condition) VALUE INSTANCE

Package

trivial-channels

Source

trivial-channels.lisp (file)

Function: channel-q-mutex INSTANCE

Function: (setf channel-q-mutex) VALUE INSTANCE

Package

trivial-channels

Source

trivial-channels.lisp (file)

Function: channel-queue INSTANCE

Function: (setf channel-queue) VALUE INSTANCE

Package

trivial-channels

Source

trivial-channels.lisp (file)

Function: copy-channel INSTANCE

Package

trivial-channels

Source

trivial-channels.lisp (file)

Function: copy-queue INSTANCE

Package

trivial-channels.queue

Source

trivial-channels.lisp (file)

Function: queue-p OBJECT

Package

trivial-channels.queue

Source

trivial-channels.lisp (file)

Function: wait-with-timeout CONDITION MUTEX SECONDS

By default we use TRIVIAL-TIMEOUTS; this can be changed for implementations later should it prove less-than-optimal.

Package

trivial-channels

Source

trivial-channels.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types