The cl-coroutine Reference Manual

Table of Contents

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

The cl-coroutine Reference Manual

This is the cl-coroutine Reference Manual, version 0.1, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:02:31 2018 GMT+0.


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

1 Introduction

Cl-Coroutine

CL-COROUTINE is a coroutine library for Common Lisp. It uses CL-CONT continuations library in its implementation.

Example

Coroutines can be defined using defcoroutine macro.

To use defined coroutines, first create a coroutine object with calling make-coroutine function, then just funcall to process it.

yield macro control back to the context which called the coroutine and the coroutine will resume processing at this point when it will be called again.

;; define a coroutine using DEFCOROUTINE macro
(defcoroutine example (whom)
  (format t "First greeting to: ~A~%" whom)
  (yield 1)
  (format t "Second greeting to: ~A~%" whom)
  (yield 2)
  (format t "Third greeting to: ~A~%" whom)
  (coexit 3)
  (format t "No greeting to: ~A~%" whom)
  (yield 4))
=> EXAMPLE

;; make a coroutine object
(setf coroutine (make-coroutine 'example))
=> a coroutine object

;; funcall it
(funcall coroutine "Smith")
>> First greeting to: Smith
=> 1

;; funcall again
(funcall coroutine "Johnson")
>> Second greeting to: Johnson
=> 2

;; funcall again and coexit
(funcall coroutine "Williams")
>> Third greeting to: Williams
=> 3

;; funcall after coexit just returns no value
(funcall coroutine "Brown")
=> No value

;; you can also use WITH-COROUTINE macro to set up coroutines,
;; which provides calling coroutines without explicit FUNCALL
(with-coroutine (example)
  (example "Smith")
  (example "Johnson"))
>> First greeting to: Smith
>> Second greeting to: Johnson
=> 2

Installation

You can install cl-coroutine via Quicklisp:

(ql:quickload :cl-coroutine)

Restrictions

CL-COROUTINE has some restrictions because of its dependency on CL-CONT library.

API

[Macro] defcoroutine

DEFCOROUTINE coroutine-name arg &body body => coroutine-name

Defines a new coroutine named coroutine-name that has atmost one argument as arg. The definition of coroutine is stored in the property list of coroutine-name symbol. Defined coroutines will be created using make-coroutine function.

[Macro] yield

YIELD [result] => |

Yields control back to the context which called the coroutine, passing along any multiple values that were passed to it. The coroutine will resume processing at this point when it will be called again. Any arguments passed to the next calling will be set to the coroutine's corresponding parameters implicitly.

[Macro] coexit

COEXIT [result] => |

Returns control to the context which called the coroutine, passing along any multiple values that were passed to it. The difference from yield macro is that the coroutine will never resume processing at this point anymore. If the coroutine will be called again, it will just return no value.

[Function] make-coroutine

MAKE-COROUTINE coroutine-name => coroutine

Creates and returns a coroutine corresponding to coroutine-name. The returned coroutine can be called with funcall or apply functions.

[Macro] with-coroutine

WITH-COROUTINE (coroutine-name) &body body => results

with-coroutine uses make-coroutine to create a coroutine with name coroutine-name and defines a local macro with name coroutine-name binding it with the coroutine. with-coroutine evaluates the body as an implicit progn with the macro.

Author

Copyright

Copyright (c) 2014 Masayuki Takagi (kamonama@gmail.com)

License

Licensed under the LLGPL License.


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-coroutine

Author

Masayuki Takagi

License

LLGPL

Description
Long Description

# Cl-Coroutine

CL-COROUTINE is a coroutine library for Common Lisp. It uses CL-CONT continuations library in its implementation.

## Example

Coroutines can be defined using ‘defcoroutine‘ macro.

To use defined coroutines, first create a coroutine object with calling ‘make-coroutine‘ function, then just ‘funcall‘ to process it.

‘yield‘ macro control back to the context which called the coroutine and the coroutine will resume processing at this point when it will be called again.

;; define a coroutine using DEFCOROUTINE macro
(defcoroutine example (whom)
(format t "First greeting to: ~A~%" whom)
(yield 1)
(format t "Second greeting to: ~A~%" whom)
(yield 2)
(format t "Third greeting to: ~A~%" whom)
(coexit 3)
(format t "No greeting to: ~A~%" whom)
(yield 4))
=> EXAMPLE

;; make a coroutine object
(setf coroutine (make-coroutine ’example))
=> a coroutine object

;; funcall it
(funcall coroutine "Smith")
>> First greeting to: Smith
=> 1

;; funcall again
(funcall coroutine "Johnson")
>> Second greeting to: Johnson
=> 2

;; funcall again and coexit
(funcall coroutine "Williams")
>> Third greeting to: Williams
=> 3

;; funcall after coexit just returns no value
(funcall coroutine "Brown")
=> No value

;; you can also use WITH-COROUTINE macro to set up coroutines,
;; which provides calling coroutines without explicit FUNCALL
(with-coroutine (example)
(example "Smith")
(example "Johnson"))
>> First greeting to: Smith
>> Second greeting to: Johnson
=> 2

## Installation

You can install ‘cl-coroutine‘ via Quicklisp:

(ql:quickload :cl-coroutine)

## Restrictions

CL-COROUTINE has some restrictions because of its dependency on CL-CONT library.
* special forms that CL-CONT library does not support with CALL/CC
* coroutines with very long definition might need much time to compile

## API

### [Macro] defcoroutine

DEFCOROUTINE coroutine-name arg &body body => coroutine-name

Defines a new coroutine named ‘coroutine-name‘ that has atmost one argument as ‘arg‘. The definition of coroutine is stored in the property list of ‘coroutine-name‘ symbol. Defined coroutines will be created using ‘make-coroutine‘ function.

### [Macro] yield

YIELD [result] => |

Yields control back to the context which called the coroutine, passing along any multiple values that were passed to it. The coroutine will resume processing at this point when it will be called again. Any arguments passed to the next calling will be set to the coroutine’s corresponding parameters implicitly.

### [Macro] coexit

COEXIT [result] => |

Returns control to the context which called the coroutine, passing along any multiple values that were passed to it. The difference from ‘yield‘ macro is that the coroutine will never resume processing at this point anymore. If the coroutine will be called again, it will just return no value.

### [Function] make-coroutine

MAKE-COROUTINE coroutine-name => coroutine

Creates and returns a coroutine corresponding to ‘coroutine-name‘. The returned coroutine can be called with ‘funcall‘ or ‘apply‘ functions.

### [Macro] with-coroutine

WITH-COROUTINE (coroutine-name) &body body => results

‘with-coroutine‘ uses ‘make-coroutine‘ to create a coroutine with name ‘coroutine-name‘ and defines a local macro with name ‘coroutine-name‘ binding it with the coroutine. ‘with-coroutine‘ evaluates the body as an implicit progn with the macro.

## Author

* Masayuki Takagi (kamonama@gmail.com)

## Copyright

Copyright (c) 2014 Masayuki Takagi (kamonama@gmail.com)

## License

Licensed under the LLGPL License.

Version

0.1

Dependencies
Source

cl-coroutine.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-coroutine/src

Parent

cl-coroutine (system)

Location

src/

Component

cl-coroutine.lisp (file)


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-coroutine.asd

Location

cl-coroutine.asd

Systems

cl-coroutine (system)

Packages

cl-coroutine-asd


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

4.1.2 cl-coroutine/src/cl-coroutine.lisp

Parent

src (module)

Location

src/cl-coroutine.lisp

Packages

cl-coroutine

Exported Definitions
Internal Definitions

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

5 Packages

Packages are listed by definition order.


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

5.1 cl-coroutine-asd

Source

cl-coroutine.asd

Use List

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

5.2 cl-coroutine

Source

cl-coroutine.lisp (file)

Use List
Exported Definitions
Internal Definitions

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: defcoroutine NAME (&optional ARG) &body BODY
Package

cl-coroutine

Source

cl-coroutine.lisp (file)

Macro: with-coroutine (NAME) &body BODY
Package

cl-coroutine

Source

cl-coroutine.lisp (file)


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

6.1.2 Functions

Function: make-coroutine NAME
Package

cl-coroutine

Source

cl-coroutine.lisp (file)


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

6.2 Internal definitions


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

6.2.1 Functions

Function: defcoroutine/arg NAME ARG BODY
Package

cl-coroutine

Source

cl-coroutine.lisp (file)

Function: defcoroutine/no-arg NAME BODY
Package

cl-coroutine

Source

cl-coroutine.lisp (file)


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-coroutine.asd: The cl-coroutine<dot>asd file
cl-coroutine/src: The cl-coroutine/src module
cl-coroutine/src/cl-coroutine.lisp: The cl-coroutine/src/cl-coroutine<dot>lisp file

F
File, Lisp, cl-coroutine.asd: The cl-coroutine<dot>asd file
File, Lisp, cl-coroutine/src/cl-coroutine.lisp: The cl-coroutine/src/cl-coroutine<dot>lisp file

L
Lisp File, cl-coroutine.asd: The cl-coroutine<dot>asd file
Lisp File, cl-coroutine/src/cl-coroutine.lisp: The cl-coroutine/src/cl-coroutine<dot>lisp file

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

Jump to:   C   F   L   M  

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

A.2 Functions

Jump to:   D   F   M   W  
Index Entry  Section

D
defcoroutine: Exported macros
defcoroutine/arg: Internal functions
defcoroutine/no-arg: Internal functions

F
Function, defcoroutine/arg: Internal functions
Function, defcoroutine/no-arg: Internal functions
Function, make-coroutine: Exported functions

M
Macro, defcoroutine: Exported macros
Macro, with-coroutine: Exported macros
make-coroutine: Exported functions

W
with-coroutine: Exported macros

Jump to:   D   F   M   W  

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

A.3 Variables


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

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-coroutine: The cl-coroutine system
cl-coroutine: The cl-coroutine package
cl-coroutine-asd: The cl-coroutine-asd package

P
Package, cl-coroutine: The cl-coroutine package
Package, cl-coroutine-asd: The cl-coroutine-asd package

S
System, cl-coroutine: The cl-coroutine system

Jump to:   C   P   S