erts: Add enif_consume_timeslice

6 files changed, 178 insertions, 10 deletions

diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index f00f7b9f46..18193d1150 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -174,9 +174,11 @@ ok
      millisecond has passed. This can be achieved using different approaches.
      If you have full control over the code that are to execute in the native
      function, the best approach is to divide the work into multiple chunks of
-     work and call the native function multiple times. This might, however,
-     not always be possible, e.g. when calling third party libraries. In this
-     case you typically want to dispatch the work to another thread, return
+     work and call the native function multiple times. Function 
+     <seealso marker="#enif_consume_timeslice">enif_consume_timeslice</seealso> can be
+     used this facilitate such work division. In some cases, however, this might not
+     be possible, e.g. when calling third party libraries. Then you typically want
+     to dispatch the work to another thread, return
      from the native function, and wait for the result. The thread can send
      the result back to the calling thread using message passing. Information
      about thread primitives can be found below.</p>
@@ -227,8 +229,8 @@ ok
       bit length have no support yet.</p>
        </item>
       <tag>Resource objects</tag>
-      <item><p>The use of resource objects is a way to return pointers to
-      native data structures from a NIF in a safe way. A resource object is
+      <item><p>The use of resource objects is a safe way to return pointers to
+      native data structures from a NIF. A resource object is
       just a block of memory allocated with
       <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>.
       A handle ("safe pointer") to this memory block can then be returned to Erlang by the use of
@@ -581,6 +583,31 @@ typedef enum {
     <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_wait">erl_drv_cond_wait</seealso>.
           </p></desc>
     </func>
+    <func><name><ret>int</ret><nametext>enif_consume_timeslice(ErlNifEnv *env, int percent)</nametext></name>
+    <fsummary></fsummary>
+    <desc><p>Give the runtime system a hint about how much CPU time the current NIF call has consumed
+    since last hint, or since the start of the NIF if no previous hint has been given.
+    The time is given as a <c>percent</c> of the timeslice that a process is allowed to execute Erlang
+    code until it may be suspended to give time for other runnable processes.
+    The scheduling timeslice is not an exact entity, but can usually be
+    approximated to about 1 millisecond.</p>
+    <p>Note that it is up to the runtime system to determine if and how to use this information.
+    Implementations on some platforms may use other means in order to determine consumed
+    CPU time. Lengthy NIFs should regardless of this frequently call <c>enif_consume_timeslice</c>
+    in order to determine if it is allowed to continue execution or not.</p>
+
+    <p>Returns 1 if the timeslice is exhausted, or 0 otherwise. If 1 is returned the NIF should return
+    as soon as possible in order for the process to yield.</p>
+    <p>Argument <c>percent</c> must be an integer between 1 and 100. This function
+    must only be called from a NIF-calling thread and argument <c>env</c> must be
+    the environment of the calling process.</p>
+    <p>This function is provided to better support co-operative scheduling, improve system responsiveness,
+    and make it easier to prevent misbehaviors of the VM due to a NIF monopolizing a scheduler thread.
+    It can be used to divide <seealso marker="#lengthy_work">length work</seealso> into
+    a number of repeated NIF-calls without the need to create threads.
+    See also the <seealso marker="#WARNING">warning</seealso> text at the beginning of this document.</p>
+    </desc>
+    </func>
     <func><name><ret>int</ret><nametext>enif_equal_tids(ErlNifTid tid1, ErlNifTid tid2)</nametext></name>
     <fsummary></fsummary>
     <desc><p>Same as <seealso marker="erl_driver#erl_drv_equal_tids">erl_drv_equal_tids</seealso>.
diff --git a/erts/emulator/beam/erl_nif.c b/erts/emulator/beam/erl_nif.c
index 068f904b76..d4c2b5bdcc 100644
--- a/erts/emulator/beam/erl_nif.c
+++ b/erts/emulator/beam/erl_nif.c
@@ -1443,6 +1443,19 @@ void* enif_dlsym(void* handle, const char* symbol,
     return ret;
 }
 
+int enif_consume_timeslice(ErlNifEnv* env, int percent)
+{
+    Sint reds;
+
+    ASSERT(is_proc_bound(env) && percent >= 1 && percent <= 100);
+    if (percent < 1) percent = 1;
+    else if (percent > 100) percent = 100;
+
+    reds = ((CONTEXT_REDS+99) / 100) * percent;
+    ASSERT(reds > 0 && reds <= CONTEXT_REDS);
+    BUMP_REDS(env->proc, reds);
+    return ERTS_BIF_REDS_LEFT(env->proc) == 0;
+}
 
 /***************************************************************************
  **                              load_nif/2                               **
diff --git a/erts/emulator/beam/erl_nif.h b/erts/emulator/beam/erl_nif.h
index 93e56332e1..62aebcab6c 100644
--- a/erts/emulator/beam/erl_nif.h
+++ b/erts/emulator/beam/erl_nif.h
@@ -32,10 +32,11 @@
 ** 2.0: R14A
 ** 2.1: R14B02 "vm_variant"
 ** 2.2: R14B03 enif_is_exception
-** 2.3: R15 enif_make_reverse_list
+** 2.3: R15 enif_make_reverse_list, enif_is_number
+** 2.4: R16 enif_consume_timeslice
 */
 #define ERL_NIF_MAJOR_VERSION 2
-#define ERL_NIF_MINOR_VERSION 3
+#define ERL_NIF_MINOR_VERSION 4
 
 #include <stdlib.h>
 
diff --git a/erts/emulator/beam/erl_nif_api_funcs.h b/erts/emulator/beam/erl_nif_api_funcs.h
index af27573433..2f841645e1 100644
--- a/erts/emulator/beam/erl_nif_api_funcs.h
+++ b/erts/emulator/beam/erl_nif_api_funcs.h
@@ -140,6 +140,7 @@ ERL_NIF_API_FUNC_DECL(int,enif_make_reverse_list,(ErlNifEnv*, ERL_NIF_TERM term,
 ERL_NIF_API_FUNC_DECL(int,enif_is_number,(ErlNifEnv*, ERL_NIF_TERM term));
 ERL_NIF_API_FUNC_DECL(void*,enif_dlopen,(const char* lib, void (*err_handler)(void*,const char*), void* err_arg));
 ERL_NIF_API_FUNC_DECL(void*,enif_dlsym,(void* handle, const char* symbol, void (*err_handler)(void*,const char*), void* err_arg));
+ERL_NIF_API_FUNC_DECL(int,enif_consume_timeslice,(ErlNifEnv*, int percent));
 
 /*
 ** Add new entries here to keep compatibility on Windows!!!
@@ -264,6 +265,7 @@ ERL_NIF_API_FUNC_DECL(void*,enif_dlsym,(void* handle, const char* symbol, void (
 #  define enif_is_number ERL_NIF_API_FUNC_MACRO(enif_is_number)
 #  define enif_dlopen ERL_NIF_API_FUNC_MACRO(enif_dlopen)
 #  define enif_dlsym ERL_NIF_API_FUNC_MACRO(enif_dlsym)
+#  define enif_consume_timeslice ERL_NIF_API_FUNC_MACRO(enif_consume_timeslice)
 
 /*
 ** Add new entries here
diff --git a/erts/emulator/test/nif_SUITE.erl b/erts/emulator/test/nif_SUITE.erl
index 6bd7361612..0a9d997c3b 100644
--- a/erts/emulator/test/nif_SUITE.erl
+++ b/erts/emulator/test/nif_SUITE.erl
@@ -36,7 +36,7 @@
 	 threading/1, send/1, send2/1, send3/1, send_threaded/1, neg/1, 
 	 is_checks/1,
 	 get_length/1, make_atom/1, make_string/1, reverse_list_test/1,
-	 otp_9668/1
+	 otp_9668/1, consume_timeslice/1
 	]).
 
 -export([many_args_100/100]).
@@ -63,7 +63,7 @@ all() ->
      resource_takeover, threading, send, send2, send3,
      send_threaded, neg, is_checks, get_length, make_atom,
      make_string,reverse_list_test,
-     otp_9668
+     otp_9668, consume_timeslice
     ].
 
 groups() -> 
@@ -1259,6 +1259,108 @@ otp_9668(Config) ->
     ?line verify_tmpmem(TmpMem),
     ok.
 
+consume_timeslice(Config) when is_list(Config) ->
+    CONTEXT_REDS = 2000,
+    Me = self(),
+    Go = make_ref(),
+    RedDiff = make_ref(),
+    Done = make_ref(),
+    DummyMFA = {?MODULE,dummy_call,1},
+    P = spawn(fun () ->
+		      receive Go -> ok end,
+		      {reductions, R1} = process_info(self(), reductions),
+		      1 = consume_timeslice_nif(100, false),
+		      dummy_call(111),
+		      0 = consume_timeslice_nif(90, false),
+		      dummy_call(222),
+		      1 = consume_timeslice_nif(10, false),
+		      dummy_call(333),
+		      0 = consume_timeslice_nif(25, false),
+		      0 = consume_timeslice_nif(25, false),
+		      0 = consume_timeslice_nif(25, false),
+		      1 = consume_timeslice_nif(25, false),
+		      0 = consume_timeslice_nif(25, false),
+
+		      ok = case consume_timeslice_nif(1, true) of
+			       Cnt when Cnt > 70, Cnt < 80 -> ok;
+			       Other -> Other
+			   end,
+		      dummy_call(444),
+
+		      {reductions, R2} = process_info(self(), reductions),
+		      Me ! {RedDiff, R2 - R1},
+		      exit(Done)
+	end),
+    erlang:yield(),
+
+    erlang:trace_pattern(DummyMFA, [], [local]),
+    ?line 1 = erlang:trace(P, true, [call, running, procs, {tracer, self()}]),
+
+    P ! Go,
+
+    %% receive Go -> ok end,
+    ?line {trace, P, in, _} = next_tmsg(P),
+    
+    %% consume_timeslice_nif(100),
+    %% dummy_call(111)
+    ?line {trace, P, out, _} = next_tmsg(P),
+    ?line {trace, P, in, _} = next_tmsg(P),
+    ?line {trace, P, call, {?MODULE,dummy_call,[111]}} = next_tmsg(P),
+
+    %% consume_timeslice_nif(90),
+    %% dummy_call(222)
+    ?line {trace, P, call, {?MODULE,dummy_call,[222]}} = next_tmsg(P),
+
+    %% consume_timeslice_nif(10),
+    %% dummy_call(333)
+    ?line {trace, P, out, _} = next_tmsg(P),
+    ?line {trace, P, in, _} = next_tmsg(P),
+    ?line {trace, P, call, {?MODULE,dummy_call,[333]}} = next_tmsg(P),
+
+    %% 25,25,25,25, 25
+    ?line {trace, P, out, {?MODULE,consume_timeslice_nif,2}} = next_tmsg(P),
+    ?line {trace, P, in, {?MODULE,consume_timeslice_nif,2}} = next_tmsg(P),
+
+    %% consume_timeslice(1,true)
+    %% dummy_call(444)
+    ?line {trace, P, out, DummyMFA} = next_tmsg(P),
+    ?line {trace, P, in, DummyMFA} = next_tmsg(P),
+    ?line {trace, P, call, {?MODULE,dummy_call,[444]}} = next_tmsg(P),
+
+    %% exit(Done)
+    ?line {trace, P, exit, Done} = next_tmsg(P),
+
+    ExpReds = (100 + 90 + 10 + 25*5 + 75) * CONTEXT_REDS div 100,
+    receive
+	{RedDiff, Reductions} when Reductions < (ExpReds + 10), Reductions > (ExpReds - 10) ->
+	    io:format("Reductions = ~p~n", [Reductions]),
+	    ok;
+	{RedDiff, Reductions} ->
+	    ?t:fail({unexpected_reduction_count, Reductions})
+    end,
+    
+    none = next_msg(P),
+
+    ok.
+
+next_msg(Pid) ->
+    receive
+	M -> M
+    after 100 ->
+	  none
+    end.
+
+next_tmsg(Pid) ->    
+    receive TMsg when is_tuple(TMsg),
+		      element(1, TMsg) == trace,
+		      element(2, TMsg) == Pid ->
+     	    TMsg
+     after 100 ->
+     	    none
+     end.
+
+dummy_call(_) ->    
+    ok.
 
 tmpmem() ->
     case erlang:system_info({allocator,temp_alloc}) of
@@ -1370,6 +1472,7 @@ reverse_list(_) -> ?nif_stub.
 echo_int(_) -> ?nif_stub.
 type_sizes() -> ?nif_stub.
 otp_9668_nif(_) -> ?nif_stub.
+consume_timeslice_nif(_,_) -> ?nif_stub.
 
 nif_stub_error(Line) ->
     exit({nif_not_loaded,module,?MODULE,line,Line}).
diff --git a/erts/emulator/test/nif_SUITE_data/nif_SUITE.c b/erts/emulator/test/nif_SUITE_data/nif_SUITE.c
index 03092fef5e..2504d24b51 100644
--- a/erts/emulator/test/nif_SUITE_data/nif_SUITE.c
+++ b/erts/emulator/test/nif_SUITE_data/nif_SUITE.c
@@ -1456,6 +1456,27 @@ static ERL_NIF_TERM otp_9668_nif(ErlNifEnv* env, int argc, const ERL_NIF_TERM ar
     return atom_ok;
 }
 
+static ERL_NIF_TERM consume_timeslice_nif(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])
+{
+    int percent;
+    char atom[10];
+    int do_repeat;
+
+    if (!enif_get_int(env, argv[0], &percent) ||
+	!enif_get_atom(env, argv[1], atom, sizeof(atom), ERL_NIF_LATIN1)) {
+	return enif_make_badarg(env);
+    }
+    if (strcmp(atom , "true") == 0) {
+	int cnt = 1;
+	while (enif_consume_timeslice(env, percent) == 0 && cnt < 200)
+	    cnt++;
+	return enif_make_int(env, cnt);
+    }
+    else {
+	return enif_make_int(env, enif_consume_timeslice(env, percent));
+    }
+}
+
 static ErlNifFunc nif_funcs[] =
 {
     {"lib_version", 0, lib_version},
@@ -1504,7 +1525,8 @@ static ErlNifFunc nif_funcs[] =
     {"reverse_list",1, reverse_list},
     {"echo_int", 1, echo_int},
     {"type_sizes", 0, type_sizes},
-    {"otp_9668_nif", 1, otp_9668_nif}
+    {"otp_9668_nif", 1, otp_9668_nif},
+    {"consume_timeslice_nif", 2, consume_timeslice_nif}
 };
 
 ERL_NIF_INIT(nif_SUITE,nif_funcs,load,reload,upgrade,unload)