Next: API [Contents][Index]

Overview ¶

Guile Knots is a library providing tools and patterns for programming with Guile Fibers. Guile Knots provides higher level building blocks for writing programs using Guile Fibers, including managing code that can’t run in a thread used by fibers. Also included is a web server implementation using Fibers, which while being similar to the web server provided by Fibers, can provide some benefits in specific circumstances.

1 API
Appendix A Version History
Appendix B Copying Information
Concept Index
Data Type Index
Procedure Index
Variable Index

Next: Version History, Previous: Overview, Up: Overview [Contents][Index]

1 API ¶

The following is the list of modules provided by this library.

(knots)
(knots non-blocking)
(knots parallelism)
(knots promise)
(knots queue)
(knots resource-pool)
(knots thread-pool)
(knots timeout)
(knots web-server)

Next: (knots non-blocking), Up: API [Contents][Index]

1.1.1 Procedures ¶

Procedure: call-with-default-io-waiters a ¶: Undocumented procedure.

Procedure: call-with-sigint a b ¶: Undocumented procedure.

Procedure: knots-exception-stack obj ¶: Undocumented procedure.

Procedure: knots-exception? obj ¶: Undocumented procedure.

Procedure: make-knots-exception a ¶: Undocumented procedure.

Procedure: print-backtrace-and-exception/knots _ KEY: #:port ¶: Undocumented procedure.

Procedure: wait-when-system-clock-behind ¶: Undocumented procedure.

1.1.2 Record Types ¶

Record type: &knots-exception ¶

This record type has the following fields:

stack

Next: (knots parallelism), Previous: (knots), Up: API [Contents][Index]

1.2 (knots non-blocking) ¶

Procedures

1.2.1 Procedures ¶

Procedure: non-blocking-open-socket-for-uri _ KEY: #:verify-certificate? ¶: Undocumented procedure.

Procedure: non-blocking-port a ¶: Make PORT non-blocking and return it.

Next: (knots promise), Previous: (knots non-blocking), Up: API [Contents][Index]

1.3 (knots parallelism) ¶

Macros
Procedures

1.3.1 Macros ¶

Macro: fibers-let a ¶: Let, but run each binding in a fiber in parallel.

Macro: fibers-parallel a ¶: Run each expression in parallel. If any expression raises an exception, this will be raised after all exceptions have finished.

Macro: parallelism-limiter? a ¶: Undocumented macro.

Macro: with-parallelism-limiter a ¶: Undocumented macro.

1.3.2 Procedures ¶

Procedure: call-with-parallelism-limiter a b ¶: Undocumented procedure.

Procedure: destroy-parallelism-limiter a ¶: Undocumented procedure.

Procedure: fiberize _ KEY: #:parallelism #:input-channel #:process-channel ¶: Undocumented procedure.

Procedure: fibers-batch-for-each a b . rest ¶: Call PROC on LISTS, running up to PARALLELISM-LIMIT fibers in parallel.

Procedure: fibers-batch-map a b . rest ¶: Map PROC over LISTS in parallel, with a PARALLELISM-LIMIT. If any of the invocations of PROC raise an exception, this will be raised once all of the calls to PROC have finished.

Procedure: fibers-for-each a . rest ¶: Call PROC on LISTS, running up to 20 fibers in parallel.

Procedure: fibers-map a . rest ¶: Map PROC over LISTS in parallel, running up to 20 fibers in PARALLEL. If any of the invocations of PROC raise an exception, this will be raised once all of the calls to PROC have finished.

Procedure: fibers-map-with-progress _ _ KEY: #:report ¶: Map PROC over LISTS, calling #:REPORT if specified after each invocation of PROC finishes. REPORT is passed the results for each element of LISTS, or #f if no result has been received yet.

Procedure: make-parallelism-limiter _ KEY: #:name ¶: Undocumented procedure.

Next: (knots queue), Previous: (knots parallelism), Up: API [Contents][Index]

1.4 (knots promise) ¶

Macros
Procedures

1.4.1 Macros ¶

Macro: fibers-promise? a ¶: Undocumented macro.

1.4.2 Procedures ¶

Procedure: fibers-delay a ¶: Undocumented procedure.

Procedure: fibers-force a ¶: Undocumented procedure.

Procedure: fibers-promise-reset a ¶: Undocumented procedure.

Procedure: fibers-promise-result-available? a ¶: Undocumented procedure.

Next: (knots resource-pool), Previous: (knots promise), Up: API [Contents][Index]

1.5 (knots queue) ¶

Procedures

1.5.1 Procedures ¶

Procedure: spawn-queueing-fiber a ¶: Undocumented procedure.

Next: (knots thread-pool), Previous: (knots queue), Up: API [Contents][Index]

1.6 (knots resource-pool) ¶

Macros
Parameters
Procedures
Record Types

1.6.1 Macros ¶

Macro: resource-pool-channel a ¶: Undocumented macro.

Macro: resource-pool-configuration a ¶: Undocumented macro.

Macro: resource-pool-name a ¶: Undocumented macro.

Macro: resource-pool? a ¶: Undocumented macro.

Macro: with-resource-from-pool a ¶: Undocumented macro.

1.6.2 Parameters ¶

Parameter: resource-pool-default-timeout-handler ¶

Default value:

#f

1.6.3 Procedures ¶

Procedure: call-with-resource-from-pool _ _ KEY: #:timeout #:timeout-handler #:max-waiters #:channel #:destroy-resource-on-exception? ¶: Call PROC with a resource from POOL, blocking until a resource becomes available. Return the resource once PROC has returned.

Procedure: destroy-resource-pool a ¶: Undocumented procedure.

Procedure: make-fixed-size-resource-pool _ KEY: #:delay-logger #:duration-logger #:destructor #:scheduler #:name #:default-checkout-timeout #:default-max-waiters ¶: Undocumented procedure.

Procedure: make-resource-pool _ _ KEY: #:min-size #:idle-seconds #:delay-logger #:duration-logger #:destructor #:lifetime #:scheduler #:name #:add-resources-parallelism #:default-checkout-timeout #:default-max-waiters ¶: Undocumented procedure.

Procedure: make-resource-pool-destroy-resource-exception ¶: Undocumented procedure.

Procedure: resource-pool-destroy-resource-exception? obj ¶: Undocumented procedure.

Procedure: resource-pool-destroyed-error-pool obj ¶: Undocumented procedure.

Procedure: resource-pool-destroyed-error? obj ¶: Undocumented procedure.

Procedure: resource-pool-stats _ KEY: #:timeout ¶: Undocumented procedure.

Procedure: resource-pool-timeout-error-pool obj ¶: Undocumented procedure.

Procedure: resource-pool-timeout-error? obj ¶: Undocumented procedure.

Procedure: resource-pool-too-many-waiters-error-pool obj ¶: Undocumented procedure.

Procedure: resource-pool-too-many-waiters-error-waiters-count obj ¶: Undocumented procedure.

Procedure: resource-pool-too-many-waiters-error? obj ¶: Undocumented procedure.

1.6.4 Record Types ¶

Record type: &resource-pool-destroy-resource ¶

This record type has the following fields:

Record type: &resource-pool-destroyed ¶

This record type has the following fields:

pool

Record type: &resource-pool-timeout ¶

This record type has the following fields:

pool

Record type: &resource-pool-too-many-waiters ¶

This record type has the following fields:

pool
waiters-count

Next: (knots timeout), Previous: (knots resource-pool), Up: API [Contents][Index]

1.7 (knots thread-pool) ¶

Macros
Procedures
Record Types

1.7.1 Macros ¶

Macro: fixed-size-thread-pool-channel a ¶: Undocumented macro.

Macro: fixed-size-thread-pool-current-procedures a ¶: Undocumented macro.

Macro: fixed-size-thread-pool? a ¶: Undocumented macro.

Macro: thread-pool-resource-pool a ¶: Undocumented macro.

Macro: thread-pool? a ¶: Undocumented macro.

1.7.2 Procedures ¶

Procedure: call-with-thread _ _ KEY: #:duration-logger #:checkout-timeout #:channel #:destroy-thread-on-exception? #:max-waiters ¶: Send PROC to the thread pool through CHANNEL. Return the result of PROC. If already in the thread pool, call PROC immediately.

Procedure: destroy-thread-pool a ¶: Undocumented procedure.

Procedure: make-fixed-size-thread-pool _ KEY: #:thread-initializer #:thread-destructor #:delay-logger #:duration-logger #:thread-lifetime #:expire-on-exception? #:name #:use-default-io-waiters? #:default-checkout-timeout ¶: Undocumented procedure.

Procedure: make-thread-pool _ KEY: #:min-size #:scheduler #:thread-initializer #:thread-destructor #:delay-logger #:duration-logger #:thread-lifetime #:expire-on-exception? #:name #:use-default-io-waiters? #:default-checkout-timeout ¶: Return a channel used to offload work to a dedicated thread. ARGS are the arguments of the thread pool procedure.

Procedure: set-thread-name a ¶: Set the name of the calling thread to NAME. NAME is truncated to 15 bytes.

Procedure: thread-name ¶: Return the name of the calling thread as a string.

Procedure: thread-pool-arguments-parameter a ¶: Undocumented procedure.

Procedure: thread-pool-default-checkout-timeout a ¶: Undocumented procedure.

Procedure: thread-pool-timeout-error-pool obj ¶: Undocumented procedure.

Procedure: thread-pool-timeout-error? obj ¶: Undocumented procedure.

1.7.3 Record Types ¶

Record type: &thread-pool-timeout-error ¶

This record type has the following fields:

pool

Next: (knots web-server), Previous: (knots thread-pool), Up: API [Contents][Index]

1.8 (knots timeout) ¶

Procedures
Record Types

1.8.1 Procedures ¶

Procedure: port-read-timeout-error? obj ¶: Undocumented procedure.

Procedure: port-timeout-error? obj ¶: Undocumented procedure.

Procedure: port-write-timeout-error? obj ¶: Undocumented procedure.

Procedure: wait-until-port-readable-operation a ¶: Make an operation that will succeed when PORT is readable.

Procedure: wait-until-port-writable-operation a ¶: Make an operation that will succeed when PORT is writable.

Procedure: with-fibers-timeout _ KEY: #:timeout #:on-timeout ¶: Undocumented procedure.

Procedure: with-port-timeouts _ KEY: #:timeout #:read-timeout #:write-timeout ¶: Undocumented procedure.

1.8.2 Record Types ¶

Record type: &port-read-timeout-error ¶

This record type has the following fields:

thunk
port

Record type: &port-timeout-error ¶

This record type has the following fields:

thunk
port

Record type: &port-write-timeout-error ¶

This record type has the following fields:

thunk
port

Previous: (knots timeout), Up: API [Contents][Index]

1.9 (knots web-server) ¶

Macros
Procedures
Record Types

1.9.1 Macros ¶

Macro: web-server-port a ¶: Undocumented macro.

Macro: web-server-socket a ¶: Undocumented macro.

Macro: web-server? a ¶: Undocumented macro.

1.9.2 Procedures ¶

Procedure: default-write-response-exception-handler a b ¶: Undocumented procedure.

Procedure: make-chunked-output-port/knots _ KEY: #:keep-alive? #:buffering ¶: Returns a new port which translates non-encoded data into a HTTP chunked transfer encoded data and writes this to PORT. Data written to this port is buffered until the port is flushed, at which point it is all sent as one chunk. The port will otherwise be flushed every BUFFERING bytes, which defaults to 1200. Take care to close the port when done, as it will output the remaining data, and encode the final zero chunk. When the port is closed it will also close PORT, unless KEEP-ALIVE? is true.

Procedure: read-request-body/knots a ¶: Undocumented procedure.

Procedure: request-body-ended-prematurely-error? obj ¶: Undocumented procedure.

Procedure: request-body-port/knots a ¶: Undocumented procedure.

Procedure: run-knots-web-server _ KEY: #:host #:family #:addr #:port #:socket #:read-request-exception-handler #:write-response-exception-handler #:connection-idle-timeout #:connection-buffer-size #:post-request-hook ¶

Run the knots web server.

HANDLER should be a procedure that takes one argument, the HTTP request and returns two values, the response and response body.

For example, here is a simple "Hello, World!" server:

 (define (handler request)
   (let ((body (read-request-body request)))
     (values '((content-type . (text/plain)))
             "Hello, World!")))
 (run-knots-web-server handler)

The response and body will be run through ‘sanitize-response’ before sending back to the client.

Procedure: sanitize-response a b c ¶

"Sanitize" the given response and body, making them appropriate for the given request.

As a convenience to web handler authors, RESPONSE may be given as an alist of headers, in which case it is used to construct a default response. Ensures that the response version corresponds to the request version. If BODY is a string, encodes the string to a bytevector, in an encoding appropriate for RESPONSE. Adds a ‘content-length’ and ‘content-type’ header, as necessary.

If BODY is a procedure, it is called with a port as an argument, and the output collected as a bytevector. In the future we might try to instead use a compressing, chunk-encoded port, and call this procedure later, in the write-client procedure. Authors are advised not to rely on the procedure being called at any particular time.

1.9.3 Record Types ¶

Record type: &request-body-ended-prematurely ¶

This record type has the following fields:

bytes-read

Next: Copying Information, Previous: API, Up: Overview [Contents][Index]

Appendix A Version History ¶

Version 0.Y.0, Month DD, 20YY

No initial release has yet been made.

Next: Concept Index, Previous: Version History, Up: Overview [Contents][Index]

Appendix B Copying Information ¶

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Next: Data Type Index, Previous: Copying Information, Up: Overview [Contents][Index]

Concept Index ¶

Next: Procedure Index, Previous: Concept Index, Up: Overview [Contents][Index]

Data Type Index ¶

&
	Index Entry	Section

	`&knots-exception`	knots
	`&port-read-timeout-error`	knots_timeout
	`&port-timeout-error`	knots_timeout
	`&port-write-timeout-error`	knots_timeout
	`&request-body-ended-prematurely`	knots_web-server
	`&resource-pool-destroy-resource`	knots_resource-pool
	`&resource-pool-destroyed`	knots_resource-pool
	`&resource-pool-timeout`	knots_resource-pool
	`&resource-pool-too-many-waiters`	knots_resource-pool
	`&thread-pool-timeout-error`	knots_thread-pool

Next: Variable Index, Previous: Data Type Index, Up: Overview [Contents][Index]

Procedure Index ¶

Jump to:	C D F K M N P R S T W

C
	Index Entry	Section

	`call-with-default-io-waiters`	knots
	`call-with-parallelism-limiter`	knots_parallelism
	`call-with-resource-from-pool`	knots_resource-pool
	`call-with-sigint`	knots
	`call-with-thread`	knots_thread-pool

D
	`default-write-response-exception-handler`	knots_web-server
	`destroy-parallelism-limiter`	knots_parallelism
	`destroy-resource-pool`	knots_resource-pool
	`destroy-thread-pool`	knots_thread-pool

F
	`fiberize`	knots_parallelism
	`fibers-batch-for-each`	knots_parallelism
	`fibers-batch-map`	knots_parallelism
	`fibers-delay`	knots_promise
	`fibers-for-each`	knots_parallelism
	`fibers-force`	knots_promise
	`fibers-let`	knots_parallelism
	`fibers-map`	knots_parallelism
	`fibers-map-with-progress`	knots_parallelism
	`fibers-parallel`	knots_parallelism
	`fibers-promise-reset`	knots_promise
	`fibers-promise-result-available?`	knots_promise
	`fibers-promise?`	knots_promise
	`fixed-size-thread-pool-channel`	knots_thread-pool
	`fixed-size-thread-pool-current-procedures`	knots_thread-pool
	`fixed-size-thread-pool?`	knots_thread-pool

K
	`knots-exception-stack`	knots
	`knots-exception?`	knots

M
	`make-chunked-output-port/knots`	knots_web-server
	`make-fixed-size-resource-pool`	knots_resource-pool
	`make-fixed-size-thread-pool`	knots_thread-pool
	`make-knots-exception`	knots
	`make-parallelism-limiter`	knots_parallelism
	`make-resource-pool`	knots_resource-pool
	`make-resource-pool-destroy-resource-exception`	knots_resource-pool
	`make-thread-pool`	knots_thread-pool

N
	`non-blocking-open-socket-for-uri`	knots_non-blocking
	`non-blocking-port`	knots_non-blocking

P
	`parallelism-limiter?`	knots_parallelism
	`port-read-timeout-error?`	knots_timeout
	`port-timeout-error?`	knots_timeout
	`port-write-timeout-error?`	knots_timeout
	`print-backtrace-and-exception/knots`	knots

R
	`read-request-body/knots`	knots_web-server
	`request-body-ended-prematurely-error?`	knots_web-server
	`request-body-port/knots`	knots_web-server
	`resource-pool-channel`	knots_resource-pool
	`resource-pool-configuration`	knots_resource-pool
	`resource-pool-destroy-resource-exception?`	knots_resource-pool
	`resource-pool-destroyed-error-pool`	knots_resource-pool
	`resource-pool-destroyed-error?`	knots_resource-pool
	`resource-pool-name`	knots_resource-pool
	`resource-pool-stats`	knots_resource-pool
	`resource-pool-timeout-error-pool`	knots_resource-pool
	`resource-pool-timeout-error?`	knots_resource-pool
	`resource-pool-too-many-waiters-error-pool`	knots_resource-pool
	`resource-pool-too-many-waiters-error-waiters-count`	knots_resource-pool
	`resource-pool-too-many-waiters-error?`	knots_resource-pool
	`resource-pool?`	knots_resource-pool
	`run-knots-web-server`	knots_web-server

S
	`sanitize-response`	knots_web-server
	`set-thread-name`	knots_thread-pool
	`spawn-queueing-fiber`	knots_queue

T
	`thread-name`	knots_thread-pool
	`thread-pool-arguments-parameter`	knots_thread-pool
	`thread-pool-default-checkout-timeout`	knots_thread-pool
	`thread-pool-resource-pool`	knots_thread-pool
	`thread-pool-timeout-error-pool`	knots_thread-pool
	`thread-pool-timeout-error?`	knots_thread-pool
	`thread-pool?`	knots_thread-pool

W
	`wait-until-port-readable-operation`	knots_timeout
	`wait-until-port-writable-operation`	knots_timeout
	`wait-when-system-clock-behind`	knots
	`web-server-port`	knots_web-server
	`web-server-socket`	knots_web-server
	`web-server?`	knots_web-server
	`with-fibers-timeout`	knots_timeout
	`with-parallelism-limiter`	knots_parallelism
	`with-port-timeouts`	knots_timeout
	`with-resource-from-pool`	knots_resource-pool

Previous: Procedure Index, Up: Overview [Contents][Index]

Variable Index ¶

R
	Index Entry	Section

	`resource-pool-default-timeout-handler`	knots_resource-pool

Guile Knots

Overview ¶

Table of Contents

1 API ¶

1.1 (knots) ¶

1.1.1 Procedures ¶

1.1.2 Record Types ¶

1.2 (knots non-blocking) ¶

1.2.1 Procedures ¶

1.3 (knots parallelism) ¶

1.3.1 Macros ¶

1.3.2 Procedures ¶

1.4 (knots promise) ¶

1.4.1 Macros ¶

1.4.2 Procedures ¶

1.5 (knots queue) ¶

1.5.1 Procedures ¶

1.6 (knots resource-pool) ¶

1.6.1 Macros ¶

1.6.2 Parameters ¶

1.6.3 Procedures ¶

1.6.4 Record Types ¶

1.7 (knots thread-pool) ¶

1.7.1 Macros ¶

1.7.2 Procedures ¶

1.7.3 Record Types ¶

1.8 (knots timeout) ¶

1.8.1 Procedures ¶

1.8.2 Record Types ¶

1.9 (knots web-server) ¶

1.9.1 Macros ¶

1.9.2 Procedures ¶

1.9.3 Record Types ¶

Appendix A Version History ¶

Appendix B Copying Information ¶

Concept Index ¶

Data Type Index ¶

Procedure Index ¶

Variable Index ¶