The bt-semaphore Reference Manual

Table of Contents

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

The bt-semaphore Reference Manual

This is the bt-semaphore Reference Manual, version 0.6.2, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 10:50:46 2018 GMT+0.


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

1 Introduction

bt-semaphore

A simple semaphore class for bordeaux-threads inspired by SBCL's semaphore.

Installation

bt-semaphore is available via Quicklisp. You can also clone the Git repo if you prefer to use bleeding edge:

cd ~/quicklisp/local-projects
git clone https://github.com/rmoritz/bt-semaphore

Usage

There are seven functions of interest at the moment:

To illustrate, here's a tiny example:

(ql:quickload :bt-semaphore)

(defun semaphore-demo ()
  (defparameter sem (bt-sem:make-semaphore))
  (defparameter lock (bt:make-lock))
  (defparameter num 0)
  
  (format t "spawn 20 threads with 4s timeout~%")
  (loop
    repeat 20
    do (bt:make-thread
         (lambda ()
           (if (bt-sem:wait-on-semaphore sem :timeout 4)
             (bt:with-lock-held (lock)
               (incf num))))))
  (format t "num is ~d~%" num)
  (sleep 0.33)
  (format t "there are ~d waiting threads~%~%" (bt-sem:semaphore-waiters sem))

  (format t "signal 5 threads~%")
  (bt-sem:signal-semaphore sem 5)
  (sleep 0.33)
  (bt:with-lock-held (lock)
    (format t "num is ~d~%" num))
  (format t "there are ~d waiting threads~%~%" (bt-sem:semaphore-waiters sem))

  (format t "signal 10 threads~%")
  (bt-sem:signal-semaphore sem 10)
  (sleep 0.33)
  (bt:with-lock-held (lock)
    (format t "num is ~d~%" num))
  (format t "there are ~d waiting threads~%~%" (bt-sem:semaphore-waiters sem))

  (format t "4s sleep~%")
  (sleep 4)
  (bt:with-lock-held (lock)
    (format t "num is ~d~%" num))
  (format t "there are ~d waiting threads~%~%" (bt-sem:semaphore-waiters sem)))

Calling SEMAPHORE-DEMO at the REPL should produce the following output:

spawn 20 threads with 4s timeout
num is 0
there are 20 waiting threads

signal 5 threads
num is 5
there are 15 waiting threads

signal 10 threads
num is 15
there are 5 waiting threads

4s sleep
num is 15
there are 0 waiting threads

Status

The basics are done. It's not yet a replacement for SB-THREAD:SEMAPHORE, but we're getting there.

You can run the test suites to verify that everything is working as it should by invoking (ql:quickload :bt-semaphore-test) or (asdf:test-system :bt-semaphore).

Bugs

I'm not aware of any bugs, but if you believe you've found one, please do report it.

Author

License

Copyright (c) Ralph Moeritz 2013.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


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 bt-semaphore

Author

Ralph Möritz

License

MIT

Description

A simple semaphore class for bordeaux-threads inspired by SBCL’s semaphore.

Long Description

# bt-semaphore

A simple semaphore class for bordeaux-threads inspired by SBCL’s semaphore.

## Installation

‘bt-semaphore‘ is available via [Quicklisp](http://www.quicklisp.org/beta/). You can also clone the Git repo if you prefer to use bleeding edge:

“‘
cd ~/quicklisp/local-projects
git clone https://github.com/rmoritz/bt-semaphore
“‘

## Usage

There are seven functions of interest at the moment:

- ‘make-semaphore‘ creates a semaphore instance
- ‘wait-on-semaphore‘ blocks until the semaphore can be decremented (ie. its count > 0) or the timeout has expired
- ‘signal-semaphore‘ increments the semaphore & wakes n waiting threads
- ‘try-semaphore‘ decrements the semaphore without blocking
- ‘semaphore-count‘ returns the current count of the semaphore
- ‘semaphore-waiters‘ returns the number of threads waiting on semaphore
- ‘semaphore-name‘ is an accessor for the semaphore’s name slot

To illustrate, here’s a tiny example:

“‘common-lisp
(ql:quickload :bt-semaphore)

(defun semaphore-demo ()
(defparameter sem (bt-sem:make-semaphore))
(defparameter lock (bt:make-lock))
(defparameter num 0)

(format t "spawn 20 threads with 4s timeout~%")
(loop
repeat 20
do (bt:make-thread
(lambda ()
(if (bt-sem:wait-on-semaphore sem :timeout 4)
(bt:with-lock-held (lock)
(incf num))))))
(format t "num is ~d~%" num)
(sleep 0.33)
(format t "there are ~d waiting threads~%~%" (bt-sem:semaphore-waiters sem))

(format t "signal 5 threads~%")
(bt-sem:signal-semaphore sem 5)
(sleep 0.33)
(bt:with-lock-held (lock)
(format t "num is ~d~%" num))
(format t "there are ~d waiting threads~%~%" (bt-sem:semaphore-waiters sem))

(format t "signal 10 threads~%")
(bt-sem:signal-semaphore sem 10)
(sleep 0.33)
(bt:with-lock-held (lock)
(format t "num is ~d~%" num))
(format t "there are ~d waiting threads~%~%" (bt-sem:semaphore-waiters sem))

(format t "4s sleep~%")
(sleep 4)
(bt:with-lock-held (lock)
(format t "num is ~d~%" num))
(format t "there are ~d waiting threads~%~%" (bt-sem:semaphore-waiters sem))) “‘

Calling ‘SEMAPHORE-DEMO‘ at the REPL should produce the following output:

“‘
spawn 20 threads with 4s timeout
num is 0
there are 20 waiting threads

signal 5 threads
num is 5
there are 15 waiting threads

signal 10 threads
num is 15
there are 5 waiting threads

4s sleep
num is 15
there are 0 waiting threads
“‘

## Status

The basics are done. It’s not yet a replacement for ‘SB-THREAD:SEMAPHORE‘, but we’re getting there.

You can run the test suites to verify that everything is working as it should by invoking ‘(ql:quickload :bt-semaphore-test)‘ or ‘(asdf:test-system :bt-semaphore)‘.

## Bugs

I’m not aware of any bugs, but if you believe you’ve found one, please do [report it](https://github.com/rmoritz/bt-semaphore/issues).

## Author

* Ralph Moeritz (ralphmoritz@outlook.com)

## License

Copyright (c) Ralph Moeritz 2013.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

**THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.**

Version

0.6.2

Dependency

bordeaux-threads

Source

bt-semaphore.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 bt-semaphore/src

Parent

bt-semaphore (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 bt-semaphore.asd

Location

bt-semaphore.asd

Systems

bt-semaphore (system)

Packages

bt-semaphore-asd


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

4.1.2 bt-semaphore/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

bt-semaphore


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

4.1.3 bt-semaphore/src/semaphore.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/semaphore.lisp

Exported Definitions
Internal Definitions

semaphore (class)


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

5 Packages

Packages are listed by definition order.


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

5.1 bt-semaphore-asd

Source

bt-semaphore.asd

Use List

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

5.2 bt-semaphore

Source

package.lisp (file)

Nickname

bt-sem

Use List
Exported Definitions
Internal Definitions

semaphore (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 Functions

Function: make-semaphore &key NAME COUNT

Create a semaphore with the supplied name and count.

Package

bt-semaphore

Source

semaphore.lisp (file)


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

6.1.2 Generic functions

Generic Function: semaphore-count INSTANCE
Package

bt-semaphore

Methods
Method: semaphore-count (INSTANCE semaphore)

Return the count of the semaphore.

Source

semaphore.lisp (file)

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

bt-semaphore

Methods
Method: semaphore-name (SEMAPHORE semaphore)

automatically generated reader method

Source

semaphore.lisp (file)

Method: (setf semaphore-name) NEW-VALUE (SEMAPHORE semaphore)

automatically generated writer method

Source

semaphore.lisp (file)

Generic Function: semaphore-waiters INSTANCE
Package

bt-semaphore

Methods
Method: semaphore-waiters (INSTANCE semaphore)

Return the number of threads waiting on the semaphore.

Source

semaphore.lisp (file)

Generic Function: signal-semaphore INSTANCE &optional N
Package

bt-semaphore

Methods
Method: signal-semaphore (INSTANCE semaphore) &optional N

Increment the count of the semaphore instance by n. If there are threads waiting on this semaphore, then n of them are woken up.

Source

semaphore.lisp (file)

Generic Function: try-semaphore INSTANCE &optional N
Package

bt-semaphore

Methods
Method: try-semaphore (INSTANCE semaphore) &optional N

Try to decrement the count of semaphore by n. Returns nil if the count were to become negative, otherwise returns t.

Source

semaphore.lisp (file)

Generic Function: wait-on-semaphore INSTANCE &key TIMEOUT
Package

bt-semaphore

Methods
Method: wait-on-semaphore (INSTANCE semaphore) &key TIMEOUT

Decrement the count of the semaphore instance if the count would not be negative, else block until the semaphore can be decremented. Returns t on success. If timeout is given, it is the maximum number of seconds to wait. If the count cannot be decremented in that time, return nil.

Source

semaphore.lisp (file)


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

6.2 Internal definitions


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

6.2.1 Classes

Class: semaphore ()
Package

bt-semaphore

Source

semaphore.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: lock
Initform

(bordeaux-threads:make-lock)

Slot: condvar
Initform

(bordeaux-threads:make-condition-variable)

Slot: count
Initargs

:count

Slot: waiters
Initform

0

Slot: name
Initargs

:name

Readers

semaphore-name (generic function)

Writers

(setf semaphore-name) (generic function)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   B   F   L   M  
Index Entry  Section

B
bt-semaphore.asd: The bt-semaphore<dot>asd file
bt-semaphore/src: The bt-semaphore/src module
bt-semaphore/src/package.lisp: The bt-semaphore/src/package<dot>lisp file
bt-semaphore/src/semaphore.lisp: The bt-semaphore/src/semaphore<dot>lisp file

F
File, Lisp, bt-semaphore.asd: The bt-semaphore<dot>asd file
File, Lisp, bt-semaphore/src/package.lisp: The bt-semaphore/src/package<dot>lisp file
File, Lisp, bt-semaphore/src/semaphore.lisp: The bt-semaphore/src/semaphore<dot>lisp file

L
Lisp File, bt-semaphore.asd: The bt-semaphore<dot>asd file
Lisp File, bt-semaphore/src/package.lisp: The bt-semaphore/src/package<dot>lisp file
Lisp File, bt-semaphore/src/semaphore.lisp: The bt-semaphore/src/semaphore<dot>lisp file

M
Module, bt-semaphore/src: The bt-semaphore/src module

Jump to:   B   F   L   M  

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

A.2 Functions

Jump to:   (  
F   G   M   S   T   W  
Index Entry  Section

(
(setf semaphore-name): Exported generic functions
(setf semaphore-name): Exported generic functions

F
Function, make-semaphore: Exported functions

G
Generic Function, (setf semaphore-name): Exported generic functions
Generic Function, semaphore-count: Exported generic functions
Generic Function, semaphore-name: Exported generic functions
Generic Function, semaphore-waiters: Exported generic functions
Generic Function, signal-semaphore: Exported generic functions
Generic Function, try-semaphore: Exported generic functions
Generic Function, wait-on-semaphore: Exported generic functions

M
make-semaphore: Exported functions
Method, (setf semaphore-name): Exported generic functions
Method, semaphore-count: Exported generic functions
Method, semaphore-name: Exported generic functions
Method, semaphore-waiters: Exported generic functions
Method, signal-semaphore: Exported generic functions
Method, try-semaphore: Exported generic functions
Method, wait-on-semaphore: Exported generic functions

S
semaphore-count: Exported generic functions
semaphore-count: Exported generic functions
semaphore-name: Exported generic functions
semaphore-name: Exported generic functions
semaphore-waiters: Exported generic functions
semaphore-waiters: Exported generic functions
signal-semaphore: Exported generic functions
signal-semaphore: Exported generic functions

T
try-semaphore: Exported generic functions
try-semaphore: Exported generic functions

W
wait-on-semaphore: Exported generic functions
wait-on-semaphore: Exported generic functions

Jump to:   (  
F   G   M   S   T   W  

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

A.3 Variables

Jump to:   C   L   N   S   W  
Index Entry  Section

C
condvar: Internal classes
count: Internal classes

L
lock: Internal classes

N
name: Internal classes

S
Slot, condvar: Internal classes
Slot, count: Internal classes
Slot, lock: Internal classes
Slot, name: Internal classes
Slot, waiters: Internal classes

W
waiters: Internal classes

Jump to:   C   L   N   S   W  

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

A.4 Data types

Jump to:   B   C   P   S  
Index Entry  Section

B
bt-semaphore: The bt-semaphore system
bt-semaphore: The bt-semaphore package
bt-semaphore-asd: The bt-semaphore-asd package

C
Class, semaphore: Internal classes

P
Package, bt-semaphore: The bt-semaphore package
Package, bt-semaphore-asd: The bt-semaphore-asd package

S
semaphore: Internal classes
System, bt-semaphore: The bt-semaphore system

Jump to:   B   C   P   S