source: project/release/4/sendfile/trunk/sendfile.html @ 18693

Last change on this file since 18693 was 18693, checked in by sjamaan, 11 years ago

sendfile: Update docs

File size: 10.9 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2<!-- Generated by eggdoc Revision: 1.20  -->
3<html>
4<head>
5<title>Eggs Unlimited - sendfile</title><style type="text/css">
6<!--
7       CODE {
8             color: #666666;
9           }
10 /*   DT.definition EM { font-weight: bold; font-style: normal; } */
11;      DT.definition { 
12                    background: #eee;
13                   color: black;
14                   padding: 0.2em 1em 0.2em 0.7em;
15                   margin-left: 0.2em;
16border: 1px solid #bbc;
17                   font-family: "Andale Mono", monospace;
18                   /* font-size: 1.2em; */
19                   
20                 }
21     DD {
22                   margin-top: 0.8em;
23                   margin-bottom: 0.8em;
24     }
25     DIV.subsection {
26                    border-top: 1px solid #448;
27                    padding-left: 1em;
28                    margin-bottom: 1.2em;
29     }
30     DIV.subsubsection {
31                    border-top: 1px dotted #99c;
32                    /* border-left: 1px solid #99c; */
33                    padding-left: 1em;
34                    margin-bottom: 1.2em;
35     }
36     DIV.subsubsubsection {
37                    border-top: 1px solid #ddf;
38                    padding-left: 1em;
39                    margin-bottom: 1.2em;
40     }
41
42         DIV.section {
43                 margin-bottom: 1.5em;
44         }
45         a:link {
46                 color: #336;
47         }
48         a:visited { color: #666; }
49         a:active  { color: #966; }
50         a:hover   { color: #669; }
51         body { margin: 0; padding: 0; background: #fff; color: #000; font: 9pt "Lucida Grande", "Verdana", sans-serif; }
52         H2 {
53                 background: #336;
54                 color: #fff;
55                 padding-top: 0.5em;
56                 padding-bottom: 0.5em;
57                 padding-left: 16px;
58                 margin: 0 0 1em 0;
59        }
60        UL LI {
61                list-style: none;
62        }
63        TT {
64                font-family: "Andale Mono", monospace;
65                /* font-size: 1.2em; */
66        }
67        H3 {
68                color: #113;
69                margin-bottom: 0.5em;
70        }
71        H4, H5, H6 {
72                color: #113;
73                margin-bottom: 1.0em;
74        }
75        H5 {
76                font-weight: normal;
77                font-style: italic;
78                font-size: 100%;
79                margin-top: 1.2em;
80        }
81        H6 {
82                font-weight: bold;
83                font-size: 85%;
84                margin-top: 1.2em;
85        }
86     DIV#eggheader {
87         text-align: center;
88                 float: right;
89                 margin-right: 2em;
90     }
91     DIV#header IMG {
92            /* display: block; margin-left: auto; margin-right: auto;  */
93            /* float: right; */
94            border: none;  /* firefox */
95     }
96     DIV#footer {
97                background: #bbd;
98                padding: 0.7em ;
99                border-top: 1px solid #cce;
100     }
101     DIV#footer hr {
102                display: none;
103     }
104     DIV#footer a {
105                float: left;
106     }
107     DIV#revision-history {
108         float: right;
109     }
110     
111     DIV#body {
112                 margin: 1em 1em 1em 16px;
113         }
114
115     DIV#examples PRE {
116       background: #eef;
117       padding: 0.1em;
118       border: 1px solid #aac;
119     }
120     PRE#license, DIV#examples PRE {
121       padding: 0.5em;
122     }
123     DIV#examples PRE {
124       /* font-size: 85%; */
125     }
126     PRE { font-family: "Andale Mono", monospace; }
127     TABLE {
128       background: #eef;
129       padding: 0.2em;
130       border: 1px solid #aac;
131       border-collapse: collapse;
132       width: 100%;
133     }
134     TABLE.symbol-table TD.symbol {
135          width: 15em;
136          font-family: "Andale Mono", monospace;
137          /* font-size: 1.2em; */
138     }
139     TH {
140       text-align: left;
141       border-bottom: 1px solid #aac;
142       padding: 0.25em 0.5em 0.25em 0.5em;
143     } 
144     TD { padding: 0.25em 0.5em 0.25em 0.5em; }
145     --></style></head>
146<body>
147<div id="header">
148<h2>sendfile</h2>
149<div id="eggheader"><a href="index.html">
150<img src="egg.jpg" alt="[Picture of an egg]" /></a></div></div>
151<div id="body">
152<div class="section">
153<h3>Description</h3>faster filetransfer over the network</div>
154<div class="section">
155<h3>Author</h3>David Krentzlin</div>
156<div class="section">
157<h3>Version</h3>
158<ul>
159<li>1.7 Actually allow input ports for source; they still have to have an underlying file descriptor currently</li>
160<li>1.6.3 Use c-pointer instead of treating the buffer as a string. Thanks to Felix</li>
161<li>1.6.2 Flush output port before sending to ensure output is sent in order.</li>
162<li>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.</li>
163<li>1.4.3 MacOS X 10.5 support, fix of BSD &amp; default 'sendfile_implementation' argument order, better error information</li>
164<li>1.3.0 make it compile on windows</li>
165<li>1.2.0 allmost complete rewrite</li>
166<li>1.1.0 Enhanced portability</li>
167<li>1.0.0 Initial release</li></ul></div>
168<div class="section">
169<h3>Usage</h3><tt>(require-extension sendfile)</tt></div>
170<div class="section">
171<h3>Download</h3><a href="sendfile.egg">sendfile.egg</a></div>
172<div class="section">
173<h3>Documentation</h3>
174<p>This extension provides a way to do filetransfers with zero-copy-semantics if applicable. It provides an interface to the sendfile syscall on
175 systems that support it. On other systems it emulates it with the help of memory-mapped IO. Sendfile is very configurable and tries to do the best based
176 on the actual file. See below to learn what it provides.</p>
177<p>NOTE: theoretically read-write-loop and mmapped-io can be used for file-to-file-transfers, where sendfile can only be used for file-network-transfers.</p>
178<div class="subsection">
179<h4>sending a file. the main interface</h4>
180<dl>
181<dt class="definition"><strong>procedure:</strong> (sendfile source destination)</dt>
182<dd>
183<p>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.</p>
184<p>source ... can be either a port to the inputfile or a filedescriptor of an already opened file.
185<p>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.</p></p></dd></dl></div>
186<div class="subsection">
187<h4>sending a file with the sendfile-syscall</h4>
188<dl>
189<dt class="definition"><strong>procedure:</strong> (sendfile:sendfile source destination len)</dt>
190<dd>
191<p>If it is available this is the interface to the sendfile-implementation of your operating system</p>
192<p>source ... is the filedescriptor of an already opened file</p>
193<p>destination ... is the filedescriptor of an already opened file (MUST be a socket)</p>
194<p>len ... is the size of the file in bytes as e.g. retrieved by (file-size)</p>
195<p>This procedure returns the amount of bytes successfully written.</p></dd></dl></div>
196<div class="subsection">
197<h4>sending a file with memory-mapped-io</h4>
198<dl>
199<dt class="definition"><strong>procedure:</strong> (sendfile:mmapped source destination len)</dt>
200<dd>
201<p>Sends a file by mapping it into the memory and do repeated writes.</p>
202<p>source ... is the filedescriptor of an already opened file</p>
203<p>destination ... is the filedescriptor of an already opened file (can be a socket)</p>
204<p>len ... is the size of the file in bytes as e.g. retrieved by (file-size)</p>
205<p>This procedure returns the amount of bytes successfully written.</p></dd></dl></div>
206<div class="subsection">
207<h4>sending a file with a read-write-loop</h4>
208<dl>
209<dt class="definition"><strong>procedure:</strong> (sendfile:read-write-loop source destination len)</dt>
210<dd>
211<p>Sends a file by performing repeated reads and writes.</p>
212<p>source ... is the filedescriptor of an already opened file</p>
213<p>destination ... is the filedescriptor of an already opened file (can be a socket)</p>
214<p>len ... is the size of the file in bytes as e.g. retrieved by (file-size)</p>
215<p>This procedure returns the amount of bytes successfully written.</p></dd></dl></div>
216<div class="subsection">
217<h4>test if sendfile is natively available</h4>
218<dl>
219<dt class="definition">sendfile:os-dep:sendfile-available?</dt>
220<dd>
221<p>Is set to #t if the sendfile-syscall is available and #f if not</p></dd></dl></div>
222<div class="subsection">
223<h4>test if mmap() is available</h4>
224<dl>
225<dt class="definition">sendfile:os-dep:mmap-available?</dt>
226<dd>
227<p>Is set to #t if the mmap() is available and #f if not</p></dd></dl></div>
228<div class="subsection">
229<h4>Parameters</h4>
230<dl>
231<dt class="definition"><strong>parameter:</strong> sendfile:read-write-buffer-size</dt>
232<dd>
233<p>The size of the buffer that is used in sendfile:read-write-loop</p></dd>
234<dt class="definition"><strong>parameter:</strong> sendfile:force-implementation</dt>
235<dd>
236<p>Causes sendfile to allways use the transmission-method specified by this parameter.
237             Possible values are 'sendfile,'mmapped,'read-write and 'nothing.
238            It defaults to 'nothing, where (sendfile) will decide which method to use based on the system's capabilities and sendfile:implementation-selector</p></dd>
239<dt class="definition"><strong>parameter:</strong> sendfile:implementation-selector</dt>
240<dd>
241<p>A one-argument procedure that gets the size of the file in question passed and is expected to return a procedure to use (either of sendfile:mmapped,sendfile:sendfile,sendfile:read-write-loop)</p></dd></dl></div>
242<div class="section">
243<h3>Examples</h3>
244<div id="examples">
245<pre>(use sendfile)
246
247;;in all the examples
248;;we use a generic procedure with-prepared-environment
249;;which we assume provides us with the input and outputports
250;;needed. Most of the time the output-port will be a socket
251;;and the input-port may be connected to a file
252;;the size of the input-file was gathered as well
253
254
255;; use the standard interface and let the system decide what to do
256(with-prepared-environment
257 (lambda (in out len)
258   (sendfile in out)))
259
260;; force a specific method to use: Part I
261
262;;read-write
263;;notice that you can force a specific transmission method
264;;via the srfi parameter sendfile:force-implementation
265;;there are four possible values: 'sendfile,'read-write-loop,'mmapped,'nothing
266;;'nothing is the default, if this is set, sendfile will decide which implementation to use
267;;based on the systems capabilities and the filesize
268(with-prepared-environment
269 (lambda (in out len)
270   (parameterize ((sendfile:force-implementation 'read-write))
271     (sendfile in out))))
272
273;;force a specific method to use: Part II
274
275;;sometimes you may want to decide which method to
276;;use based on the size of the file.
277;;there is an srfi-parameter called sendfile:implementation-selector
278;;which does just that. See documentation for details
279(with-prepared-environment
280 (lambda (in out)
281   (paramaterize ((sendfile:implementation-selector) (lambda (len)
282                                                       (if (&gt; len 1024)
283                                                           sendfile:sendfile
284                                                           sendfile:read-write-loop)))
285                 (sendfile in out))))
286</pre></div></div></div></div>
287<div id="footer">
288<hr /><a href="index.html">&lt; Egg index</a>
289<div id="revision-history">$Revision$ $Date$</div>&nbsp;</div></body></html>
Note: See TracBrowser for help on using the repository browser.