The trivial-channels Reference Manual

Table of Contents

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 2.3 "Robert April" on Wed Mar 14 04:40:15 2018 GMT+0.


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

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.


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 trivial-channels

Author

Ryan Pavlik

License

BSD-2-Clause

Description

Really simple channels and queue

Version

1.0

Dependencies
Source

trivial-channels.asd (file)

Components

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

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 files   [Contents][Index]

3.1.1 trivial-channels.asd

Location

trivial-channels.asd

Systems

trivial-channels (system)

Packages

trivial-channels.asdf


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

3.1.2 trivial-channels/package.lisp

Parent

trivial-channels (system)

Location

package.lisp

Packages

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

3.1.3 trivial-channels/trivial-channels.lisp

Dependency

package.lisp (file)

Parent

trivial-channels (system)

Location

trivial-channels.lisp

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 trivial-channels.asdf

Source

trivial-channels.asd

Use List

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

4.2 trivial-channels

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

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

4.3 trivial-channels.queue

Source

package.lisp (file)

Use List

common-lisp

Used By List

trivial-channels

Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


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

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)


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

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)


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

5.2 Internal definitions


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

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)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   T  
Index Entry  Section

F
File, Lisp, trivial-channels.asd: The trivial-channels<dot>asd file
File, Lisp, trivial-channels/package.lisp: The trivial-channels/package<dot>lisp file
File, Lisp, trivial-channels/trivial-channels.lisp: The trivial-channels/trivial-channels<dot>lisp file

L
Lisp File, trivial-channels.asd: The trivial-channels<dot>asd file
Lisp File, trivial-channels/package.lisp: The trivial-channels/package<dot>lisp file
Lisp File, trivial-channels/trivial-channels.lisp: The trivial-channels/trivial-channels<dot>lisp file

T
trivial-channels.asd: The trivial-channels<dot>asd file
trivial-channels/package.lisp: The trivial-channels/package<dot>lisp file
trivial-channels/trivial-channels.lisp: The trivial-channels/trivial-channels<dot>lisp file

Jump to:   F   L   T  

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): Internal functions
(setf channel-q-mutex): Internal functions
(setf channel-queue): Internal functions
(setf queue-head): Exported functions
(setf queue-tail): Exported functions

C
channel-p: Internal functions
channel-q-condition: Internal functions
channel-q-mutex: Internal functions
channel-queue: Internal functions
copy-channel: Internal functions
copy-queue: Internal functions

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

G
getmsg: Exported functions

H
hasmsg: Exported functions

M
make-channel: Exported functions
make-queue: Exported functions

Q
queue-add: Exported functions
queue-add-cons: Exported functions
queue-has-item-p: Exported functions
queue-head: Exported functions
queue-p: Internal functions
queue-peek: Exported functions
queue-pop: Exported functions
queue-pop-cons: Exported functions
queue-pop-to: Exported functions
queue-prepend-to: Exported functions
queue-push: Exported functions
queue-tail: Exported functions

R
recvmsg: Exported functions

S
sendmsg: Exported functions

W
wait-with-timeout: Internal functions

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

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

A.3 Variables

Jump to:   H   Q   S   T  
Index Entry  Section

H
head: Exported structures

Q
q-condition: Exported structures
q-mutex: Exported structures
queue: Exported structures

S
Slot, head: Exported structures
Slot, q-condition: Exported structures
Slot, q-mutex: Exported structures
Slot, queue: Exported structures
Slot, tail: Exported structures

T
tail: Exported structures

Jump to:   H   Q   S   T  

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

A.4 Data types

Jump to:   C   P   Q   S   T  
Index Entry  Section

C
channel: Exported structures

P
Package, trivial-channels: The trivial-channels package
Package, trivial-channels.asdf: The trivial-channels<dot>asdf package
Package, trivial-channels.queue: The trivial-channels<dot>queue package

Q
queue: Exported structures

S
Structure, channel: Exported structures
Structure, queue: Exported structures
System, trivial-channels: The trivial-channels system

T
trivial-channels: The trivial-channels system
trivial-channels: The trivial-channels package
trivial-channels.asdf: The trivial-channels<dot>asdf package
trivial-channels.queue: The trivial-channels<dot>queue package

Jump to:   C   P   Q   S   T