From 758fab8895755b22ce02f0a6026d4d286c8a9c5a Mon Sep 17 00:00:00 2001
From: Lukas Larsson <garazdawi@gmail.com>
Date: Sun, 27 Nov 2011 17:30:06 +0100
Subject: Expand sendfile documentation

---
 lib/kernel/doc/src/file.xml | 66 ++++++++++++++++++++++++++++++++++++++-------
 lib/kernel/src/file.erl     | 18 ++++++-------
 2 files changed, 66 insertions(+), 18 deletions(-)

diff --git a/lib/kernel/doc/src/file.xml b/lib/kernel/doc/src/file.xml
index 78bf0aff45..7fcc354176 100644
--- a/lib/kernel/doc/src/file.xml
+++ b/lib/kernel/doc/src/file.xml
@@ -149,6 +149,9 @@
     <datatype>
       <name name="mode"/>
     </datatype>
+    <datatype>
+      <name name="sendfile_option"/>
+    </datatype>
    </datatypes>
 
   <funcs>
@@ -1574,25 +1577,70 @@
       </desc>
     </func>
     <func>
-      <name name="sendfile" arity="4"/>
+      <name name="sendfile" arity="2"/>
       <fsummary>send a file to a socket</fsummary>
       <desc>
-        <p>Sends <c>Bytes</c> in from the file
-        referenced by <c>IoDevice</c> beginning at <c>Offset</c> to
-        <c>Socket</c>.
+        <p>Sends the file <c>Filename</c> to <c>Socket</c>.
         Returns <c>{ok, BytesSent}</c> if successful,
         otherwise <c>{error, Reason}</c>.</p>
-        <p>Available on Linux, FreeBSD, DragonflyBSD, Solaris, Darwin and Windows</p>
       </desc>
     </func>
     <func>
-      <name name="sendfile" arity="2"/>
+      <name name="sendfile" arity="5"/>
       <fsummary>send a file to a socket</fsummary>
       <desc>
-        <p>Sends the file <c>Filename</c> to <c>Socket</c>.
+        <p>Sends <c>Bytes</c> from the file
+        referenced by <c>RawFile</c> beginning at <c>Offset</c> to
+        <c>Socket</c>.
         Returns <c>{ok, BytesSent}</c> if successful,
-        otherwise <c>{error, Reason}</c>.</p>
-        <p>Available on Linux, FreeBSD, DragonflyBSD, Solaris, Darwin and Windows</p>
+        otherwise <c>{error, Reason}</c>. If <c>Bytes</c> is set to
+	0 all data after the given <c>Offset</c> is sent.</p>
+	<p>The file used must be opened using the raw flag, and the process
+	calling sendfile must be the controlling process of the socket.
+	See <seealso marker="gen_tcp#controlling_process-2">gen_tcp:controlling_process/2</seealso></p>
+	<p>If the OS used does not support sendfile, an Erlang fallback
+	using file:read and gen_tcp:send is used.</p>
+	<p>The option list can contain the following options:
+	<taglist>
+          <tag><c>headers</c></tag>
+          <item>A list containing data which is to be sent before
+	  the file is sent. If <c>headers</c> is used, <c>Bytes</c> specifies
+	  the total bytes in the header and/or file to be sent. If
+	  <c>Bytes</c> is set to 0, the all headers, the file and
+	  possible trailers will be sent. </item>
+          <tag><c>trailers</c></tag>
+          <item>A list containing data which is to be after before
+	  the file is sent. All the <c>trailers</c> will be sent after the
+	  file is sent, no matter what <c>Bytes</c> is set to. </item>
+          <tag><c>chunk_size</c></tag>
+          <item>The chunk size used by the erlang fallback to send
+	  data. If using the fallback, this should be set to a value
+	  which comfortably fits in the systems memory. Default is 20 MB.</item>
+          <tag><c>sf_nodiskio</c></tag>
+          <item>This flag causes any sendfile() call which would
+	   block on disk I/O to instead return EBUSY.  Busy servers may bene-
+	   fit by transferring requests that would block to a separate I/O
+	   worker thread.</item>
+          <tag><c>sf_mnowait</c></tag>
+          <item>Do not wait for some kernel resource to become avail-
+	   able, in particular, mbuf and sf_buf.  The flag does not make the
+	   sendfile() syscall truly non-blocking, since other resources are
+	   still allocated in a blocking fashion.</item>
+          <tag><c>sf_sync</c></tag>
+          <item>sendfile sleeps until the network stack no longer refer-
+	   ences the VM pages of the file, making subsequent modifications to
+	   it safe.  Please note that this is not a guarantee that the data
+	   has actually been sent.</item>
+	</taglist>
+	</p>
+	<p>On operating systems with thread support, it is recommended to use
+	async threads. See the command line flag
+	<c>+A</c> in <seealso marker="erts:erl">erl(1)</seealso>. If it is not
+	possible to use async threads for sendfile, it is recommended to use
+	a relatively small value for the send buffer on the socket. Otherwise
+	the Erlang VM might loose some of its soft realtime guarantees.
+	Which size to use depends on the OS/hardware and the requirements
+	of the application.</p>
       </desc>
     </func>
     <func>
diff --git a/lib/kernel/src/file.erl b/lib/kernel/src/file.erl
index ef1d20b53b..19eaa7bfcc 100644
--- a/lib/kernel/src/file.erl
+++ b/lib/kernel/src/file.erl
@@ -106,7 +106,7 @@
 -type date_time() :: calendar:datetime().
 -type posix_file_advise() :: 'normal' | 'sequential' | 'random'
                            | 'no_reuse' | 'will_need' | 'dont_need'.
--type sendfile_option() :: {chunk_size, non_neg_integer()} |
+-type sendfile_option() :: {chunk_size, pos_integer()} |
 			   {headers, Hdrs :: list(iodata())} |
 			   {trailers, Tlrs :: list(iodata())} |
 			   sf_nodiskio | sf_mnowait | sf_sync.
@@ -1126,10 +1126,10 @@ change_time(Name, Atime, Mtime)
 
 -define(MAX_CHUNK_SIZE, (1 bsl 20)*20). %% 20 MB, has to fit in primary memory
 
--spec sendfile(File, Sock, Offset, Bytes, Opts) ->
+-spec sendfile(RawFile, Socket, Offset, Bytes, Opts) ->
    {'ok', non_neg_integer()} | {'error', inet:posix() | badarg | not_owner} when
-      File :: file:fd(),
-      Sock :: inet:socket(),
+      RawFile :: file:fd(),
+      Socket :: inet:socket(),
       Offset :: non_neg_integer(),
       Bytes :: non_neg_integer(),
       Opts :: [sendfile_option()].
@@ -1151,12 +1151,12 @@ sendfile(File, Sock, Offset, Bytes, Opts) ->
 	     lists:member(sf_sync,Opts)).
 
 %% sendfile/2
--spec sendfile(File, Sock) ->
+-spec sendfile(Filename, Socket) ->
    {'ok', non_neg_integer()} | {'error', inet:posix() | badarg | not_owner}
-      when File :: file:name(),
-	   Sock :: inet:socket().
-sendfile(File, Sock)  ->
-    case file:open(File, [read, raw, binary]) of
+      when Filename :: file:name(),
+	   Socket :: inet:socket().
+sendfile(Filename, Sock)  ->
+    case file:open(Filename, [read, raw, binary]) of
 	{error, Reason} ->
 	    {error, Reason};
 	{ok, Fd} ->
-- 
cgit v1.2.3