Add file:advise/4 - a wrapper to the POSIX syscall posix_fadvise

Useful for informing the Operating System about the access pattern
for a file's data, so that it can adapt the caching strategy to
maximize disk IO performance.

6 files changed, 224 insertions, 4 deletions

diff --git a/lib/kernel/doc/src/file.xml b/lib/kernel/doc/src/file.xml
index c94df62d1f..382262d1ee 100644
--- a/lib/kernel/doc/src/file.xml
+++ b/lib/kernel/doc/src/file.xml
@@ -62,6 +62,25 @@ time() = {{Year, Month, Day}, {Hour, Minute, Second}}
   </section>
   <funcs>
     <func>
+      <name>advise(IoDevice, Offset, Length, Advise) -> ok | {error, Reason}</name>
+      <fsummary>Predeclare an access pattern for file data</fsummary>
+      <type>
+        <v>IoDevice = io_device()</v>
+        <v>Offset = int()</v>
+        <v>Length = int()</v>
+        <v>Advise = posix_file_advise()</v>
+        <v>posix_file_advise() = normal | sequential | random | no_reuse
+          | will_need | dont_need</v>
+        <v>Reason = ext_posix()</v>
+      </type>
+      <desc>
+        <p><c>advise/4</c> can be used to announce an intention to access file
+          data in a specific pattern in the future, thus allowing the
+          operating system to perform appropriate optimizations.</p>
+        <p>On some platforms, this function might have no effect.</p>
+      </desc>
+    </func>
+    <func>
       <name>change_group(Filename, Gid) -> ok | {error, Reason}</name>
       <fsummary>Change group of a file</fsummary>
       <type>
diff --git a/lib/kernel/src/file.erl b/lib/kernel/src/file.erl
index 5da359fdf1..a694ed0708 100644
--- a/lib/kernel/src/file.erl
+++ b/lib/kernel/src/file.erl
@@ -36,7 +36,7 @@
 %% Specialized
 -export([ipread_s32bu_p32bu/3]).
 %% Generic file contents.
--export([open/2, close/1, 
+-export([open/2, close/1, advise/4,
 	 read/2, write/2, 
 	 pread/2, pread/3, pwrite/2, pwrite/3,
 	 read_line/1,
@@ -89,6 +89,8 @@
 -type date()      :: {pos_integer(), pos_integer(), pos_integer()}.
 -type time()      :: {non_neg_integer(), non_neg_integer(), non_neg_integer()}.
 -type date_time() :: {date(), time()}.
+-type posix_file_advise() :: 'normal' | 'sequential' | 'random' | 'no_reuse' |
+                            'will_need' | 'dont_need'.
 
 %%%-----------------------------------------------------------------
 %%% General functions
@@ -352,6 +354,18 @@ close(#file_descriptor{module = Module} = Handle) ->
 close(_) ->
     {error, badarg}.
 
+-spec advise(File :: io_device(), Offset :: integer(),
+        Length :: integer(), Advise :: posix_file_advise()) ->
+	'ok' | {'error', posix()}.
+
+advise(File, Offset, Length, Advise) when is_pid(File) ->
+    R = file_request(File, {advise, Offset, Length, Advise}),
+    wait_file_reply(File, R);
+advise(#file_descriptor{module = Module} = Handle, Offset, Length, Advise) ->
+    Module:advise(Handle, Offset, Length, Advise);
+advise(_, _, _, _) ->
+    {error, badarg}.
+
 -spec read(File :: io_device(), Size :: non_neg_integer()) ->
 	'eof' | {'ok', [char()] | binary()} | {'error', posix()}.
 
diff --git a/lib/kernel/src/file_io_server.erl b/lib/kernel/src/file_io_server.erl
index d0b30192b3..39dc32bb79 100644
--- a/lib/kernel/src/file_io_server.erl
+++ b/lib/kernel/src/file_io_server.erl
@@ -198,6 +198,14 @@ io_reply(From, ReplyAs, Reply) ->
 %%%-----------------------------------------------------------------
 %%% file requests
 
+file_request({advise,Offset,Length,Advise},
+         #state{handle=Handle}=State) ->
+    case ?PRIM_FILE:advise(Handle, Offset, Length, Advise) of
+    {error,_}=Reply ->
+        {stop,normal,Reply,State};
+    Reply ->
+        {reply,Reply,State}
+    end;
 file_request({pread,At,Sz}, 
 	     #state{handle=Handle,buf=Buf,read_mode=ReadMode}=State) ->
     case position(Handle, At, Buf) of
diff --git a/lib/kernel/src/ram_file.erl b/lib/kernel/src/ram_file.erl
index 0230cb4e0a..2bfb2cd021 100644
--- a/lib/kernel/src/ram_file.erl
+++ b/lib/kernel/src/ram_file.erl
@@ -28,7 +28,7 @@
 
 %% Specialized file operations
 -export([get_size/1, get_file/1, set_file/2, get_file_close/1]).
--export([compress/1, uncompress/1, uuencode/1, uudecode/1]).
+-export([compress/1, uncompress/1, uuencode/1, uudecode/1, advise/4]).
 
 -export([open_mode/1]).  %% used by ftp-file
 
@@ -71,6 +71,7 @@
 -define(RAM_FILE_UUENCODE,       35).
 -define(RAM_FILE_UUDECODE,       36).
 -define(RAM_FILE_SIZE,           37).
+-define(RAM_FILE_ADVISE,         38).
 
 %% Open modes for RAM_FILE_OPEN
 -define(RAM_FILE_MODE_READ,       1).
@@ -91,6 +92,14 @@
 -define(RAM_FILE_RESP_NUMBER,     3).
 -define(RAM_FILE_RESP_INFO,       4).
 
+%% POSIX file advises
+-define(POSIX_FADV_NORMAL,     0).
+-define(POSIX_FADV_RANDOM,     1).
+-define(POSIX_FADV_SEQUENTIAL, 2).
+-define(POSIX_FADV_WILLNEED,   3).
+-define(POSIX_FADV_DONTNEED,   4).
+-define(POSIX_FADV_NOREUSE,    5).
+
 %% --------------------------------------------------------------------------
 %% Generic file contents operations.
 %%
@@ -352,6 +361,28 @@ uudecode(#file_descriptor{module = ?MODULE, data = Port}) ->
 uudecode(#file_descriptor{}) ->
     {error, enotsup}.
 
+advise(#file_descriptor{module = ?MODULE, data = Port}, Offset,
+        Length, Advise) ->
+    Cmd0 = <<?RAM_FILE_ADVISE, Offset:64/signed, Length:64/signed>>,
+    case Advise of
+    normal ->
+        call_port(Port, <<Cmd0/binary, ?POSIX_FADV_NORMAL:32/signed>>);
+    random ->
+        call_port(Port, <<Cmd0/binary, ?POSIX_FADV_RANDOM:32/signed>>);
+    sequential ->
+        call_port(Port, <<Cmd0/binary, ?POSIX_FADV_SEQUENTIAL:32/signed>>);
+    will_need ->
+        call_port(Port, <<Cmd0/binary, ?POSIX_FADV_WILLNEED:32/signed>>);
+    dont_need ->
+        call_port(Port, <<Cmd0/binary, ?POSIX_FADV_DONTNEED:32/signed>>);
+    no_reuse ->
+        call_port(Port, <<Cmd0/binary, ?POSIX_FADV_NOREUSE:32/signed>>);
+    _ ->
+        {error, einval}
+    end;
+advise(#file_descriptor{}, _Offset, _Length, _Advise) ->
+    {error, enotsup}.
+
 
 
 %%%-----------------------------------------------------------------
diff --git a/lib/kernel/test/file_SUITE.erl b/lib/kernel/test/file_SUITE.erl
index 2e6c3aba16..1d652679b0 100644
--- a/lib/kernel/test/file_SUITE.erl
+++ b/lib/kernel/test/file_SUITE.erl
@@ -82,6 +82,8 @@
 
 -export([read_line_1/1, read_line_2/1, read_line_3/1,read_line_4/1]).
 
+-export([advise/1]).
+
 %% Debug exports
 -export([create_file_slow/2, create_file/2, create_bin/2]).
 -export([verify_file/2, verify_bin/3]).
@@ -377,7 +379,9 @@ win_cur_dir_1(_Config) ->
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-files(suite) -> [open,pos,file_info,consult,eval,script,truncate,sync,datasync].
+files(suite) ->
+    [open,pos,file_info,consult,eval,script,truncate,
+     sync,datasync,advise].
 
 open(suite) -> [open1,old_modes,new_modes,path_open,close,access,read_write,
 	       pread_write,append,open_errors].
@@ -1402,6 +1406,77 @@ sync(Config) when is_list(Config) ->
     ?line test_server:timetrap_cancel(Dog),
     ok.
 
+advise(suite) -> [];
+advise(doc) -> "Tests that ?FILE_MODULE:advise/4 at least doesn't crash.";
+advise(Config) when is_list(Config) ->
+    ?line Dog = test_server:timetrap(test_server:seconds(5)),
+    ?line PrivDir = ?config(priv_dir, Config),
+    ?line Advise = filename:join(PrivDir,
+			       atom_to_list(?MODULE)
+			       ++"_advise.fil"),
+
+    Line1 = "Hello\n",
+    Line2 = "World!\n",
+
+    ?line {ok, Fd} = ?FILE_MODULE:open(Advise, [write]),
+    ?line ok = ?FILE_MODULE:advise(Fd, 0, 0, normal),
+    ?line ok = io:format(Fd, "~s", [Line1]),
+    ?line ok = io:format(Fd, "~s", [Line2]),
+    ?line ok = ?FILE_MODULE:close(Fd),
+
+    ?line {ok, Fd2} = ?FILE_MODULE:open(Advise, [write]),
+    ?line ok = ?FILE_MODULE:advise(Fd2, 0, 0, random),
+    ?line ok = io:format(Fd2, "~s", [Line1]),
+    ?line ok = io:format(Fd2, "~s", [Line2]),
+    ?line ok = ?FILE_MODULE:close(Fd2),
+
+    ?line {ok, Fd3} = ?FILE_MODULE:open(Advise, [write]),
+    ?line ok = ?FILE_MODULE:advise(Fd3, 0, 0, sequential),
+    ?line ok = io:format(Fd3, "~s", [Line1]),
+    ?line ok = io:format(Fd3, "~s", [Line2]),
+    ?line ok = ?FILE_MODULE:close(Fd3),
+
+    ?line {ok, Fd4} = ?FILE_MODULE:open(Advise, [write]),
+    ?line ok = ?FILE_MODULE:advise(Fd4, 0, 0, will_need),
+    ?line ok = io:format(Fd4, "~s", [Line1]),
+    ?line ok = io:format(Fd4, "~s", [Line2]),
+    ?line ok = ?FILE_MODULE:close(Fd4),
+
+    ?line {ok, Fd5} = ?FILE_MODULE:open(Advise, [write]),
+    ?line ok = ?FILE_MODULE:advise(Fd5, 0, 0, dont_need),
+    ?line ok = io:format(Fd5, "~s", [Line1]),
+    ?line ok = io:format(Fd5, "~s", [Line2]),
+    ?line ok = ?FILE_MODULE:close(Fd5),
+
+    ?line {ok, Fd6} = ?FILE_MODULE:open(Advise, [write]),
+    ?line ok = ?FILE_MODULE:advise(Fd6, 0, 0, no_reuse),
+    ?line ok = io:format(Fd6, "~s", [Line1]),
+    ?line ok = io:format(Fd6, "~s", [Line2]),
+    ?line ok = ?FILE_MODULE:close(Fd6),
+
+    ?line {ok, Fd7} = ?FILE_MODULE:open(Advise, [write]),
+    ?line {error, einval} = ?FILE_MODULE:advise(Fd7, 0, 0, bad_advise),
+    ?line ok = ?FILE_MODULE:close(Fd7),
+
+    %% test write without advise, then a read after an advise
+    ?line {ok, Fd8} = ?FILE_MODULE:open(Advise, [write]),
+    ?line ok = io:format(Fd8, "~s", [Line1]),
+    ?line ok = io:format(Fd8, "~s", [Line2]),
+    ?line ok = ?FILE_MODULE:close(Fd8),
+    ?line {ok, Fd9} = ?FILE_MODULE:open(Advise, [read]),
+    Offset = 0,
+    %% same as a 0 length in some implementations
+    Length = length(Line1) + length(Line2),
+    ?line ok = ?FILE_MODULE:advise(Fd9, Offset, Length, sequential),
+    ?line {ok, Line1} = ?FILE_MODULE:read_line(Fd9),
+    ?line {ok, Line2} = ?FILE_MODULE:read_line(Fd9),
+    ?line eof = ?FILE_MODULE:read_line(Fd9),
+    ?line ok = ?FILE_MODULE:close(Fd9),
+
+    ?line [] = flush(),
+    ?line test_server:timetrap_cancel(Dog),
+    ok.
+
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
diff --git a/lib/kernel/test/prim_file_SUITE.erl b/lib/kernel/test/prim_file_SUITE.erl
index 842945e83c..21bdc06fdc 100644
--- a/lib/kernel/test/prim_file_SUITE.erl
+++ b/lib/kernel/test/prim_file_SUITE.erl
@@ -48,6 +48,8 @@
 	 symlinks_a/1, symlinks_b/1,
 	 list_dir_limit/1]).
 
+-export([advise/1]).
+
 -include("test_server.hrl").
 -include_lib("kernel/include/file.hrl").
 
@@ -380,7 +382,7 @@ win_cur_dir_1(_Config, Handle) ->
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-files(suite) -> [open,pos,file_info,truncate,sync,datasync].
+files(suite) -> [open,pos,file_info,truncate,sync,datasync,advise].
 
 open(suite) -> [open1,modes,close,access,read_write,
 	       pread_write,append].
@@ -1100,6 +1102,77 @@ sync(Config) when is_list(Config) ->
     ok.
 
 
+advise(suite) -> [];
+advise(doc) -> "Tests that ?PRIM_FILE:advise/4 at least doesn't crash.";
+advise(Config) when is_list(Config) ->
+    ?line Dog = test_server:timetrap(test_server:seconds(5)),
+    ?line PrivDir = ?config(priv_dir, Config),
+    ?line Advise = filename:join(PrivDir,
+			       atom_to_list(?MODULE)
+			       ++"_advise.fil"),
+
+    Line1 = "Hello\n",
+    Line2 = "World!\n",
+
+    ?line {ok, Fd} = ?PRIM_FILE:open(Advise, [write]),
+    ?line ok = ?PRIM_FILE:advise(Fd, 0, 0, normal),
+    ?line ok = ?PRIM_FILE:write(Fd, Line1),
+    ?line ok = ?PRIM_FILE:write(Fd, Line2),
+    ?line ok = ?PRIM_FILE:close(Fd),
+
+    ?line {ok, Fd2} = ?PRIM_FILE:open(Advise, [write]),
+    ?line ok = ?PRIM_FILE:advise(Fd2, 0, 0, random),
+    ?line ok = ?PRIM_FILE:write(Fd2, Line1),
+    ?line ok = ?PRIM_FILE:write(Fd2, Line2),
+    ?line ok = ?PRIM_FILE:close(Fd2),
+
+    ?line {ok, Fd3} = ?PRIM_FILE:open(Advise, [write]),
+    ?line ok = ?PRIM_FILE:advise(Fd3, 0, 0, sequential),
+    ?line ok = ?PRIM_FILE:write(Fd3, Line1),
+    ?line ok = ?PRIM_FILE:write(Fd3, Line2),
+    ?line ok = ?PRIM_FILE:close(Fd3),
+
+    ?line {ok, Fd4} = ?PRIM_FILE:open(Advise, [write]),
+    ?line ok = ?PRIM_FILE:advise(Fd4, 0, 0, will_need),
+    ?line ok = ?PRIM_FILE:write(Fd4, Line1),
+    ?line ok = ?PRIM_FILE:write(Fd4, Line2),
+    ?line ok = ?PRIM_FILE:close(Fd4),
+
+    ?line {ok, Fd5} = ?PRIM_FILE:open(Advise, [write]),
+    ?line ok = ?PRIM_FILE:advise(Fd5, 0, 0, dont_need),
+    ?line ok = ?PRIM_FILE:write(Fd5, Line1),
+    ?line ok = ?PRIM_FILE:write(Fd5, Line2),
+    ?line ok = ?PRIM_FILE:close(Fd5),
+
+    ?line {ok, Fd6} = ?PRIM_FILE:open(Advise, [write]),
+    ?line ok = ?PRIM_FILE:advise(Fd6, 0, 0, no_reuse),
+    ?line ok = ?PRIM_FILE:write(Fd6, Line1),
+    ?line ok = ?PRIM_FILE:write(Fd6, Line2),
+    ?line ok = ?PRIM_FILE:close(Fd6),
+
+    ?line {ok, Fd7} = ?PRIM_FILE:open(Advise, [write]),
+    ?line {error, einval} = ?PRIM_FILE:advise(Fd7, 0, 0, bad_advise),
+    ?line ok = ?PRIM_FILE:close(Fd7),
+
+    %% test write without advise, then a read after an advise
+    ?line {ok, Fd8} = ?PRIM_FILE:open(Advise, [write]),
+    ?line ok = ?PRIM_FILE:write(Fd8, Line1),
+    ?line ok = ?PRIM_FILE:write(Fd8, Line2),
+    ?line ok = ?PRIM_FILE:close(Fd8),
+    ?line {ok, Fd9} = ?PRIM_FILE:open(Advise, [read]),
+    Offset = 0,
+    %% same as a 0 length in some implementations
+    Length = length(Line1) + length(Line2),
+    ?line ok = ?PRIM_FILE:advise(Fd9, Offset, Length, sequential),
+    ?line {ok, Line1} = ?PRIM_FILE:read_line(Fd9),
+    ?line {ok, Line2} = ?PRIM_FILE:read_line(Fd9),
+    ?line eof = ?PRIM_FILE:read_line(Fd9),
+    ?line ok = ?PRIM_FILE:close(Fd9),
+
+    ?line test_server:timetrap_cancel(Dog),
+    ok.
+
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 delete_a(suite) -> [];