source: project/wiki/eggref/5/sendfile @ 38758

Last change on this file since 38758 was 38758, checked in by Mario Domenech Goulart, 7 weeks ago

eggref/5/sendfile: fix comment in example (the value for force-implementation' is 'read-write', not `'read-write-loop'.

File size: 6.8 KB
Line 
1[[tags: egg]]
2
3== Sendfile
4
5[[toc:]]
6
7=== Introduction
8This 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
9uses some other techniques to emulate it on systems that don't.
10
11=== Requirements
12
13* [[memory-mapped-files]]
14
15=== Repository
16
17[[https://bitbucket.org/certainty/sendfile/overview]]
18
19=== API
20
21<procedure>(sendfile source destination  #!key (offset 0) (bytes #f))</procedure>
22Tries 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.
23{{source}}  can be either a port to the inputfile or a filedescriptor of an already opened file.
24{{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.
25{{offset}} If given the procedure seeks to {{offset}} bytes and starts to transfer from there on
26{{bytes}} If given it transfers only {{bytes}} bytes of data.
27
28<procedure>(impl:mmapped src dst len #!key (offset 0.0))</procedure>
29Sends a file by mapping it into the memory and do repeated writes.
30{{source}} is the filedescriptor of an already opened file.
31{{destination}} is the filedescriptor of an already opened file (can be a socket).
32{{len}} is the size of the file in bytes as e.g. retrieved by (file-size).
33{{offset}} is the offset where to start the read.
34This procedure returns the amount of bytes successfully written.
35
36<procedure>(impl:sendfile src dst len)</procedure>
37If it is available this is the interface to the sendfile-implementation of your operating system
38{{source}} is the filedescriptor of an already opened file.
39{{destination}} is the filedescriptor of an already opened file (MUST be a socket).
40{{len}} is the size of the file in bytes as e.g. retrieved by (file-size).
41This procedure returns the amount of bytes successfully written.
42
43<procedure> (impl:read-write-loop/port src dst len)</procedure>
44Sends a file by performing repeated reads and writes where the source is a port.
45{{source}}  is  the input-port.
46{{destination}} is the filedescriptor of an already opened file (can be a socket).
47{{len}} is the size of the file in bytes as e.g. retrieved by (file-size).
48This procedure returns the amount of bytes successfully written.
49
50<procedure> (impl:read-write-loop/fd src dst len)</procedure>
51
52
53<parameter>force-implementation</parameter>
54Causes 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.
55
56<parameter>implementation-selector</parameter>
57A one-argument procedure that gets the size of the file in question passed and is expected to return a procedure to use.
58
59=== Examples
60<enscript highlight=scheme>
61(import sendfile)
62
63;;in all the examples
64;;we use a generic procedure with-prepared-environment
65;;which we assume provides us with the input and outputports
66;;needed. Most of the time the output-port will be a socket
67;;and the input-port may be connected to a file
68;;the size of the input-file was gathered as well
69;; use the standard interface and let the system decide what to do
70
71(with-prepared-environment
72 (lambda (in out len)
73   (sendfile in out)))
74
75;; force a specific method to use: Part I
76
77;;read-write
78;;notice that you can force a specific transmission method
79;;via the srfi parameter force-implementation
80;;there are four possible values: 'sendfile,'read-write,'mmapped,'nothing
81;;'nothing is the default, if this is set, sendfile will decide which implementation to use
82;;based on the systems capabilities and the filesize
83(with-prepared-environment
84 (lambda (in out len)
85   (parameterize ((force-implementation 'read-write))
86     (sendfile in out))))
87
88;;force a specific method to use: Part II
89
90;;sometimes you may want to decide which method to
91;;use based on the size of the file.
92;;there is an srfi-parameter called implementation-selector
93;;which does just that. See documentation for details
94(with-prepared-environment
95 (lambda (in out)
96   (parameterize ((implementation-selector) (lambda (len)
97                                                       (if (> len 1024)
98                                                           impl:sendfile
99                                                           impl:read-write-loop)))
100                 (sendfile in out))))
101
102</enscript>
103
104=== Authors
105[[/users/david-krentzlin|David Krentzlin]]
106
107with lots of help from:
108[[/users/peter-bex|Peter Bex]],
109[[/users/jim-ursetto|Jim Ursetto]] and
110[[/users/felix-winkelmann|Felix Winkelmann]]
111
112
113=== License
114  Copyright (c) 2007 David Krentzlin
115 
116  Permission is hereby granted, free of charge, to any person obtaining a
117  copy of this software and associated documentation files (the "Software"),
118  to deal in the Software without restriction, including without limitation
119  the rights to use, copy, modify, merge, publish, distribute, sublicense,
120  and/or sell copies of the Software, and to permit persons to whom the
121  Software is furnished to do so, subject to the following conditions:
122 
123  The above copyright notice and this permission notice shall be included
124  in all copies or substantial portions of the Software.
125 
126  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
127  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
128  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
129  THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
130  OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
131  ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
132  OTHER DEALINGS IN THE SOFTWARE.
133
134=== Version history
135
136* 1.8.3 Added shebang line to shell build script.
137* 1.8.2 Fixed build for platforms where the sendfile implementation is unsupported, so it matches the CHICKEN 4 build.
138* 1.8.1 Fixed dependency on memory-mapped-files
139* 1.8.0 First CHICKEN 5 release
140* 1.7.4 Both input and output can be ports now.
141* 1.7 Actually allow input ports for source; they still have to have an underlying file descriptor currently
142* 1.6.3 Use c-pointer instead of treating the buffer as a string. Thanks to Felix
143* 1.6.2 Flush output port before sending to ensure output is sent in order.
144* 1.5.0 The 'force parameter has been removed from (sendfile), its a parameter now instead. Bugfix for the read-write-loop, that causes corrupted files to be sent.
145* 1.4.3 MacOS X 10.5 support, fix of BSD & default 'sendfile_implementation' argument order, better error information
146* 1.3.0 make it compile on windows
147* 1.2.0 allmost complete rewrite
148* 1.1.0 Enhanced portability
149* 1.0.0 Initial release
Note: See TracBrowser for help on using the repository browser.