[erlang-questions] purpose of enif_schedule_dirty_nif_finalizer

[Steve Vinoski]

On Tue, Feb 11, 2014 at 4:38 PM, Vincent Siliakus <zambal@REDACTED> wrote:

> I'm experimenting a bit with the new dirty scheduler functionality for
> NIFs and have already some working code, but I was wondering what the
> purpose is of enif_schedule_dirty_nif_finalizer and
> enif_dirty_nif_finalizer.
>
> I know documentation about dirty schedulers should be coming when OTP
> 17.0 is released, but maybe somebody can already give some pointers
> about how and why they should be used.


Below find the descriptions that are in the 17.0 documentation sources on
github master. If you have further questions, let me know. BTW both
descriptions are accompanied by this note:

This function is available only when the emulator is configured with dirty
schedulers enabled. This feature is currently disabled by default. To
determine whether the dirty NIF API is available, native code can check to
see if the C preprocessor macro ERL_NIF_DIRTY_SCHEDULER_SUPPORT is defined.

Oh, and all of this is subject to change, of course, as this is an
experimental feature of 17.0.

--steve


ERL_NIF_TERM enif_schedule_dirty_nif_finalizer(ErlNifEnv* env, ERL_NIF_TERM
result, ERL_NIF_TERM (*fp)(ErlNifEnv* env, ERL_NIF_TERM result))

When a dirty NIF finishes executing, it must schedule a finalizer function
to return its result to the original NIF caller. The dirty NIF passes
result as the value it wants the finalizer to use as the return value. The
fp argument is a pointer to the finalizer function. The NIF API provides
the enif_dirty_nif_finalizer function that can be used as a finalizer that
simply returns its result argument. You are also free to write your own
custom finalizer that uses result to derive a different return value, or
ignores result entirely and returns a completely different value.

Without exception, all dirty NIFs must invoke
enif_schedule_dirty_nif_finalizer to complete their execution.

ERL_NIF_TERM enif_dirty_nif_finalizer(ErlNifEnv* env, ERL_NIF_TERM result)

A convenience function that a dirty NIF can use as a finalizer that simply
return its result argument as its return value. This function is provided
for dirty NIFs with results that should be returned directly to the
original caller.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20140211/9fafac24/attachment.htm>