You are looking at historical revision 22476 of this page. It may differ significantly from its current revision.

Sendfile

Introduction

This eggs provides procedures to send data from a source to a destination. It tries to use the sendfile(2) syscall on systems that support it and uses some other techniques to emulate it on systems that don't.

API

[procedure] (sendfile source destination)

Tries to send the file identified by `source` to `destination` as fast as possible. Unless a specific technique is forced it will decide what method to use from the systems capabilities and the filesize. source can be either a port to the inputfile or a filedescriptor of an already opened file. destination can be either a port to the outputfile (socket) or a filedescriptor (socketdesciptor) of an already opened file (socket). When it is a port, any buffered output is flushed via flush-output prior to sending the file.

[procedure] (impl:mmapped src dst len #!key (offset 0.0))

Sends a file by mapping it into the memory and do repeated writes. source is the filedescriptor of an already opened file. destination is the filedescriptor of an already opened file (can be a socket). len is the size of the file in bytes as e.g. retrieved by (file-size). offset is the offset where to start the read. This procedure returns the amount of bytes successfully written.

[procedure] (impl:sendfile src dst len)

If it is available this is the interface to the sendfile-implementation of your operating system source is the filedescriptor of an already opened file. destination is the filedescriptor of an already opened file (MUST be a socket). len is the size of the file in bytes as e.g. retrieved by (file-size). This procedure returns the amount of bytes successfully written.

[procedure] (impl:read-write-loop/port src dst len)

Sends a file by performing repeated reads and writes where the source is a port. source is the input-port. destination is the filedescriptor of an already opened file (can be a socket). len is the size of the file in bytes as e.g. retrieved by (file-size). This procedure returns the amount of bytes successfully written.

[procedure] (impl:read-write-loop/fd src dst len)
[parameter] force-implementation

Causes sendfile to allways use the transmission-method specified by this parameter. Possible values are 'sendfile,'mmapped,'read-write and 'nothing. It defaults to 'nothing, where (sendfile) will decide which method to use based on the system's capabilities and sendfile:implementation-selector.

[parameter] implementation-selector

A one-argument procedure that gets the size of the file in question passed and is expected to return a procedure to use.

Examples

(use sendfile)

;;in all the examples
;;we use a generic procedure with-prepared-environment
;;which we assume provides us with the input and outputports
;;needed. Most of the time the output-port will be a socket
;;and the input-port may be connected to a file
;;the size of the input-file was gathered as well
;; use the standard interface and let the system decide what to do

(with-prepared-environment
 (lambda (in out len)
   (sendfile in out)))

;; force a specific method to use: Part I

;;read-write
;;notice that you can force a specific transmission method
;;via the srfi parameter force-implementation
;;there are four possible values: 'sendfile,'read-write-loop,'mmapped,'nothing
;;'nothing is the default, if this is set, sendfile will decide which implementation to use
;;based on the systems capabilities and the filesize
(with-prepared-environment
 (lambda (in out len)
   (parameterize ((force-implementation 'read-write))
     (sendfile in out))))

;;force a specific method to use: Part II

;;sometimes you may want to decide which method to
;;use based on the size of the file.
;;there is an srfi-parameter called implementation-selector
;;which does just that. See documentation for details
(with-prepared-environment
 (lambda (in out)
   (paramaterize ((implementation-selector) (lambda (len)
                                                       (if (> len 1024)
                                                           impl:sendfile
                                                           impl:read-write-loop)))
                 (sendfile in out))))

Authors

David Krentzlin

License

 Copyright (c) 2007 David Krentzlin 

 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 history