The trivial-channels Reference Manual

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

The trivial-channels Reference Manual

This is the trivial-channels Reference Manual, version 1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 06:02:33 2022 GMT+0.

Table of Contents


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

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.

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.


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

2.1 trivial-channels

Really simple channels and queue

Author

Ryan Pavlik

License

BSD-2-Clause

Version

1.0

Dependencies
  • bordeaux-threads (system).
  • trivial-timeout (system).
Source

trivial-channels.asd.

Child Components

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 trivial-channels/trivial-channels.asd

Source

trivial-channels.asd.

Parent Component

trivial-channels (system).

ASDF Systems

trivial-channels.

Packages

trivial-channels.asdf.


3.1.2 trivial-channels/package.lisp

Source

trivial-channels.asd.

Parent Component

trivial-channels (system).

Packages

3.1.3 trivial-channels/trivial-channels.lisp

Dependency

package.lisp (file).

Source

trivial-channels.asd.

Parent Component

trivial-channels (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


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

4.1 trivial-channels

Source

package.lisp.

Use List
Public Interface
Internals

4.2 trivial-channels.asdf

Source

trivial-channels.asd.

Use List
  • asdf/interface.
  • common-lisp.

4.3 trivial-channels.queue

Source

package.lisp.

Use List

common-lisp.

Used By List

trivial-channels.

Public Interface
Internals

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: getmsg (channel)
Package

trivial-channels.

Source

trivial-channels.lisp.

Function: hasmsg (channel)
Package

trivial-channels.

Source

trivial-channels.lisp.

Function: make-channel (&key queue q-condition q-mutex)
Package

trivial-channels.

Source

trivial-channels.lisp.

Function: make-queue (&key head tail)
Package

trivial-channels.queue.

Source

trivial-channels.lisp.

Function: queue-add (q item)
Package

trivial-channels.queue.

Source

trivial-channels.lisp.

Function: queue-add-cons (q cons)
Package

trivial-channels.queue.

Source

trivial-channels.lisp.

Function: queue-has-item-p (q)
Package

trivial-channels.queue.

Source

trivial-channels.lisp.

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

trivial-channels.queue.

Source

trivial-channels.lisp.

Target Slot

head.

Function: queue-peek (q)

Peek at the head of the queue.

Package

trivial-channels.queue.

Source

trivial-channels.lisp.

Function: queue-pop (q)
Package

trivial-channels.queue.

Source

trivial-channels.lisp.

Function: queue-pop-cons (q)
Package

trivial-channels.queue.

Source

trivial-channels.lisp.

Function: queue-pop-to (q1 q2)

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

Package

trivial-channels.queue.

Source

trivial-channels.lisp.

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.

Function: queue-push (q item)
Package

trivial-channels.queue.

Source

trivial-channels.lisp.

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

trivial-channels.queue.

Source

trivial-channels.lisp.

Target Slot

tail.

Function: recvmsg (channel &optional timeout)
Package

trivial-channels.

Source

trivial-channels.lisp.

Function: sendmsg (channel msg)
Package

trivial-channels.

Source

trivial-channels.lisp.


5.1.2 Structures

Structure: channel
Package

trivial-channels.

Source

trivial-channels.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: queue
Package

trivial-channels.queue.

Type

trivial-channels.queue:queue

Initform

(trivial-channels.queue:make-queue)

Readers

channel-queue.

Writers

(setf channel-queue).

Slot: q-condition
Initform

(bordeaux-threads:make-condition-variable)

Readers

channel-q-condition.

Writers

(setf channel-q-condition).

Slot: q-mutex
Initform

(bordeaux-threads:make-lock)

Readers

channel-q-mutex.

Writers

(setf channel-q-mutex).

Structure: queue
Package

trivial-channels.queue.

Source

trivial-channels.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: head
Readers

queue-head.

Writers

(setf queue-head).

Slot: tail
Readers

queue-tail.

Writers

(setf queue-tail).


5.2 Internals


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

5.2.1 Ordinary functions

Function: channel-p (object)
Package

trivial-channels.

Source

trivial-channels.lisp.

Reader: channel-q-condition (instance)
Writer: (setf channel-q-condition) (instance)
Package

trivial-channels.

Source

trivial-channels.lisp.

Target Slot

q-condition.

Reader: channel-q-mutex (instance)
Writer: (setf channel-q-mutex) (instance)
Package

trivial-channels.

Source

trivial-channels.lisp.

Target Slot

q-mutex.

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

trivial-channels.

Source

trivial-channels.lisp.

Target Slot

queue.

Function: copy-channel (instance)
Package

trivial-channels.

Source

trivial-channels.lisp.

Function: copy-queue (instance)
Package

trivial-channels.queue.

Source

trivial-channels.lisp.

Function: queue-p (object)
Package

trivial-channels.queue.

Source

trivial-channels.lisp.

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.


Appendix A Indexes


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

A.1 Concepts


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

A.2 Functions

Jump to:   (  
C   F   G   H   M   Q   R   S   W  
Index Entry  Section

(
(setf channel-q-condition): Private ordinary functions
(setf channel-q-mutex): Private ordinary functions
(setf channel-queue): Private ordinary functions
(setf queue-head): Public ordinary functions
(setf queue-tail): Public ordinary functions

C
channel-p: Private ordinary functions
channel-q-condition: Private ordinary functions
channel-q-mutex: Private ordinary functions
channel-queue: Private ordinary functions
copy-channel: Private ordinary functions
copy-queue: Private ordinary functions

F
Function, (setf channel-q-condition): Private ordinary functions
Function, (setf channel-q-mutex): Private ordinary functions
Function, (setf channel-queue): Private ordinary functions
Function, (setf queue-head): Public ordinary functions
Function, (setf queue-tail): Public ordinary functions
Function, channel-p: Private ordinary functions
Function, channel-q-condition: Private ordinary functions
Function, channel-q-mutex: Private ordinary functions
Function, channel-queue: Private ordinary functions
Function, copy-channel: Private ordinary functions
Function, copy-queue: Private ordinary functions
Function, getmsg: Public ordinary functions
Function, hasmsg: Public ordinary functions
Function, make-channel: Public ordinary functions
Function, make-queue: Public ordinary functions
Function, queue-add: Public ordinary functions
Function, queue-add-cons: Public ordinary functions
Function, queue-has-item-p: Public ordinary functions
Function, queue-head: Public ordinary functions
Function, queue-p: Private ordinary functions
Function, queue-peek: Public ordinary functions
Function, queue-pop: Public ordinary functions
Function, queue-pop-cons: Public ordinary functions
Function, queue-pop-to: Public ordinary functions
Function, queue-prepend-to: Public ordinary functions
Function, queue-push: Public ordinary functions
Function, queue-tail: Public ordinary functions
Function, recvmsg: Public ordinary functions
Function, sendmsg: Public ordinary functions
Function, wait-with-timeout: Private ordinary functions

G
getmsg: Public ordinary functions

H
hasmsg: Public ordinary functions

M
make-channel: Public ordinary functions
make-queue: Public ordinary functions

Q
queue-add: Public ordinary functions
queue-add-cons: Public ordinary functions
queue-has-item-p: Public ordinary functions
queue-head: Public ordinary functions
queue-p: Private ordinary functions
queue-peek: Public ordinary functions
queue-pop: Public ordinary functions
queue-pop-cons: Public ordinary functions
queue-pop-to: Public ordinary functions
queue-prepend-to: Public ordinary functions
queue-push: Public ordinary functions
queue-tail: Public ordinary functions

R
recvmsg: Public ordinary functions

S
sendmsg: Public ordinary functions

W
wait-with-timeout: Private ordinary functions

Jump to:   (  
C   F   G   H   M   Q   R   S   W