source: project/release/4/sendfile/tags/1.7/sendfile.doc.scm @ 18693

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

sendfile: Update docs

File size: 6.9 KB
Line 
1(use eggdoc)
2;(use eggdoc-zb)
3
4(define examples `( (pre #<<EOF
5(use sendfile)
6
7;;in all the examples
8;;we use a generic procedure with-prepared-environment
9;;which we assume provides us with the input and outputports
10;;needed. Most of the time the output-port will be a socket
11;;and the input-port may be connected to a file
12;;the size of the input-file was gathered as well
13
14
15;; use the standard interface and let the system decide what to do
16(with-prepared-environment
17 (lambda (in out len)
18   (sendfile in out)))
19
20;; force a specific method to use: Part I
21
22;;read-write
23;;notice that you can force a specific transmission method
24;;via the srfi parameter sendfile:force-implementation
25;;there are four possible values: 'sendfile,'read-write-loop,'mmapped,'nothing
26;;'nothing is the default, if this is set, sendfile will decide which implementation to use
27;;based on the systems capabilities and the filesize
28(with-prepared-environment
29 (lambda (in out len)
30   (parameterize ((sendfile:force-implementation 'read-write))
31     (sendfile in out))))
32
33;;force a specific method to use: Part II
34
35;;sometimes you may want to decide which method to
36;;use based on the size of the file.
37;;there is an srfi-parameter called sendfile:implementation-selector
38;;which does just that. See documentation for details
39(with-prepared-environment
40 (lambda (in out)
41   (paramaterize ((sendfile:implementation-selector) (lambda (len)
42                                                       (if (> len 1024)
43                                                           sendfile:sendfile
44                                                           sendfile:read-write-loop)))
45                 (sendfile in out))))
46
47EOF
48)))
49
50(define doc
51  `((eggdoc:begin
52    (name "sendfile")
53    (description "faster filetransfer over the network")
54    (author "David Krentzlin")
55    (history
56     (version "1.7" "Actually allow input ports for source; they still have to have an underlying file descriptor currently")
57     (version "1.6.3" "Use c-pointer instead of treating the buffer as a string. Thanks to Felix")
58     (version "1.6.2" "Flush output port before sending to ensure output is sent in order.")
59     (version "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.")
60     (version "1.4.3" "MacOS X 10.5 support, fix of BSD & default 'sendfile_implementation' argument order, better error information")
61     (version "1.3.0" "make it compile on windows")
62     (version "1.2.0" "allmost complete rewrite")
63     (version "1.1.0" "Enhanced portability")
64     (version "1.0.0" "Initial release"))
65    (usage)
66    (download "sendfile.egg")
67    (documentation
68     (p "This extension provides a way to do filetransfers with zero-copy-semantics if applicable. It provides an interface to the sendfile syscall on
69 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
70 on the actual file. See below to learn what it provides.")
71     
72     (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.")
73     
74     (subsection "sending a file. the main interface"
75       (group           
76        (procedure "(sendfile source destination)"
77          (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.")
78
79          (p "source ... can be either a port to the inputfile or a filedescriptor of an already opened file."
80
81          (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.")))))
82     
83     (subsection "sending a file with the sendfile-syscall"
84      (group           
85        (procedure "(sendfile:sendfile source destination len)"
86          (p "If it is available this is the interface to the sendfile-implementation of your operating system")
87
88          (p "source ... is the filedescriptor of an already opened file")
89          (p "destination ... is the filedescriptor of an already opened file (MUST be a socket)")
90          (p "len ... is the size of the file in bytes as e.g. retrieved by (file-size)")
91          (p "This procedure returns the amount of bytes successfully written."))))
92
93     (subsection "sending a file with memory-mapped-io"
94      (group           
95        (procedure "(sendfile:mmapped source destination len)"
96          (p "Sends a file by mapping it into the memory and do repeated writes.")
97          (p "source ... is the filedescriptor of an already opened file")
98          (p "destination ... is the filedescriptor of an already opened file (can be a socket)")
99          (p "len ... is the size of the file in bytes as e.g. retrieved by (file-size)")
100          (p "This procedure returns the amount of bytes successfully written."))))
101
102     (subsection "sending a file with a read-write-loop"
103      (group           
104        (procedure "(sendfile:read-write-loop source destination len)"
105          (p "Sends a file by performing repeated reads and writes.")
106
107          (p "source ... is the filedescriptor of an already opened file")
108          (p "destination ... is the filedescriptor of an already opened file (can be a socket)")
109          (p "len ... is the size of the file in bytes as e.g. retrieved by (file-size)")
110          (p "This procedure returns the amount of bytes successfully written."))))
111
112     (subsection "test if sendfile is natively available"
113      (group           
114        (definition "sendfile:os-dep:sendfile-available?"
115          (p "Is set to #t if the sendfile-syscall is available and #f if not"))))
116
117     (subsection "test if mmap() is available"
118      (group           
119        (definition "sendfile:os-dep:mmap-available?"
120          (p "Is set to #t if the mmap() is available and #f if not"))))
121
122     (subsection "Parameters"
123      (group           
124        (parameter "sendfile:read-write-buffer-size"
125          (p "The size of the buffer that is used in sendfile:read-write-loop"))
126        (parameter "sendfile:force-implementation"
127          (p "Causes sendfile to allways use the transmission-method specified by this parameter.
128             Possible values are 'sendfile,'mmapped,'read-write and 'nothing.
129            It defaults to 'nothing, where (sendfile) will decide which method to use based on the system's capabilities and sendfile:implementation-selector"))
130        (parameter "sendfile:implementation-selector"
131          (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)"))))
132         
133                   
134
135     (examples ,examples)))))
136
137(eggdoc->html doc)
Note: See TracBrowser for help on using the repository browser.