aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/erl_nif.xml
AgeCommit message (Collapse)Author
2015-11-27Merge branch 'sverk/cpool_fetch-dc_list-fix' into maintSverker Eriksson
OTP-13147 * sverk/cpool_fetch-dc_list-fix: erts: Reduce alloc_SUITE:rbtree runtime for valgrind erts: Remove double free in efile_drv erts: Improve alloc_SUITE:migration test erts: Pass free mem and build type to alloc_SUITE tests erts: Fix snprintf in alloc_SUITE for windows erts: Workaround for strange crash on win64 in alloc_SUITE test code erts: Refactor alloc_SUITE to use NIFs instead of drivers erts: Add enif_getenv erts: Make key argument constant for erl_drv_{get|put}env erts: Add alloc_SUITE:migration erts: Add TEST allocator erts: Fix confusion of callbacks destroying_mbc() vs remove_mbc() erts: Fix resurrection of carriers from dc_list
2015-11-26erts: Add enif_getenvSverker Eriksson
to read OS environment variables in a safe and portable way.
2015-11-04[erts] Correct documentationHans Bolinder
Fix mistakes found by 'xmllint'.
2015-06-18Change license text to APLv2Bruce Yinhe
2015-06-05Add forgotten argument to example in erl_nif docTomas Abrahamsson
In the documentation for erl_nif, in the map iterator example, the iterator argument was forgotten in the call to function enif_map_iterator_create. This is now fixed.
2015-06-01Merge branch 'vinoski/enif-raise-exception/OTP-12770'Sverker Eriksson
* vinoski/enif-raise-exception/OTP-12770: Add enif_raise_exception Enhance enif_has_pending_exception Fix for enif_schedule_nif and exceptions Conflicts: erts/doc/src/erl_nif.xml
2015-05-28erts: Cleanup fsummary lines in erl_nif docsSverker Eriksson
by removing all full stop.
2015-05-28erts: Fix alphabetic order in erl_nif docSverker Eriksson
enif_make_reverse_list was at the wrong place
2015-05-28erts: Add docs for map functions in nif APISverker Eriksson
2015-05-26Add enif_raise_exceptionSteve Vinoski
Add enif_raise_exception function to allow NIFs to raise error exceptions holding any Erlang terms. This does not replace or deprecate the enif_make_badarg function, though, because raising badarg errors is so idiomatic in NIFs. Reimplement enif_make_badarg on top of enif_raise_exception. Add new tests for enif_raise_exception for both normal and dirty NIFs. Add documentation for enif_raise_exception.
2015-05-26Enhance enif_has_pending_exceptionSteve Vinoski
Sverker Eriksson came up with the following idea: to handle a future ability for NIFs to raise more than just badarg exceptions, modify the recently-added enif_has_pending_exception function to take a second argument: a pointer to ERL_NIF_TERM. If this argument is a null pointer, ignore it. Otherwise, if the first argument, an ErlNifEnv*, has an associated exception, set the pointed-to ERL_NIF_TERM of the second argument to the value of the exception term. Add new tests and documentation for this modification.
2015-04-15erts: Remove old docs about experimental NIF versions.Sverker Eriksson
2015-04-15erts: Add enif_has_pending_exceptionSverker Eriksson
2015-04-15erts: Clearify erl_nif documentation about badarg exceptionSverker Eriksson
Also state that maximum atom length is 255 characters.
2015-03-15Ensure NIF term creation disallows illegal valuesSteve Vinoski
Add a check to enif_make_double to see if its double argument is infinity or NaN, returning a badarg exception if it is. Change the erl_nif documentation to specify that enif_make_double returns a badarg exception if its double argument is either infinity or NaN. Add tests to nif_SUITE for this change. Add checks to the enif_make* functions for atoms to prevent the creation of atoms whose name lengths are greater than the allowed maximum atom length. The enif_make_atom and enif_make_atom_len functions now return a badarg exception if the input string is too long. The enif_make_existing_atom and enif_make_existing_atom_len functions return false if the input string is too long. Change the erl_nif documentation to reflect the changes to these functions. Add tests to nif_SUITE for these changes. Add a field to ErlNifEnv to track that a NIF has raised an exception via enif_make_badarg. If a NIF calls enif_make_badarg but then ignores its return value and instead tries to return a non-exception term as its return value, the runtime still raises a badarg. This is needed to prevent enif_make_badarg values resulting from calls to enif_make_double, enif_make_atom, or enif_make_atom_len from being erroneously stored within other terms and returned from a NIF. Calling enif_make_badarg but not returning its return value has been documented as being illegal ever since enif_make_badarg was added, but the runtime has not enforced it until now. Add tests for regular and dirty NIFs to ensure that calls to enif_make_badarg result in badarg exceptions even if a NIF fails to return the result of enif_make_badarg as its return value. Add documentation to enif_make_badarg to specify that calling it raises a badarg even if a NIF ignores its return value.
2014-09-12erts: Remove enif_have_dirty_schedulers()Sverker Eriksson
and add 'dirty_scheduler_support' to ErlNifSysInfo
2014-08-28add enif_schedule_nif() to NIF APISteve Vinoski
In the #erlang IRC channel Anthony Ramine once mentioned the idea of allowing a NIF to use an emulator trap, similar to a BIF trap, to schedule another NIF for execution. This is exactly how dirty NIFs were implemented for Erlang/OTP 17.0, so this commit refactors and generalizes that dirty NIF code to support a new enif_schedule_nif() API function. The enif_schedule_nif() function allows a long-running NIF to be broken into separate NIF invocations. The NIF first executes part of the long-running task, then calls enif_schedule_nif() to schedule a NIF for later execution to continue the task. Any number of NIFs can be scheduled in this manner, one after another. Since the emulator regains control between invocations, this helps avoid problems caused by native code tying up scheduler threads for too long. The enif_schedule_nif() function also replaces the original experimental dirty NIF API. The function takes a flags parameter that a caller can use to indicate the NIF should be scheduled onto either a dirty CPU scheduler thread, a dirty I/O scheduler thread, or scheduled as a regular NIF on a regular scheduler thread. With this change, the original experimental enif_schedule_dirty_nif(), enif_schedule_dirty_nif_finalizer() and enif_dirty_nif_finalizer() API functions are no longer needed and have been removed. Explicit scheduling of a dirty NIF finalization function is no longer necessary; if an application wants similar functionality, it can have a dirty NIF just invoke enif_schedule_nif() to schedule a non-dirty NIF to complete its task. Lift the restriction that dirty NIFs can't call enif_make_badarg() to raise an exception. This was a problem with the original dirty NIF API because it forced developers to get and check all incoming arguments in a regular NIF, and then schedule the dirty NIF which then had to get all the arguments again. Now, the argument checking can be done in the dirty NIF and it can call enif_make_badarg() itself to flag incorrect arguments. Extend the ErlNifFunc struct with a new flags field that allows NIFs to be declared as dirty. The default value for this field is 0, indicating a regular NIF, so it's backwards compatible with all existing statically initialized ErlNifFunc struct instances, and so such instances require no code changes. Defining the flags field with a value of ERL_NIF_DIRTY_JOB_CPU_BOUND indicates that the NIF should execute on a dirty CPU scheduler thread, or defining it with a value of ERL_NIF_DIRTY_JOB_IO_BOUND indicates that the NIF should execute on a dirty I/O scheduler thread. Any other flags field value causes a NIF library loading error. Extend the ErlNifEntry struct with a new options field that indicates whether a NIF library was built with support for optional features such as dirty NIFs. When a NIF library is loaded, the runtime checks the options field to ensure compatibility. If a NIF library built with dirty NIF support is loaded into a runtime that does not support dirty NIFs, and the library defines one or more ErlNifFunc entries with non-zero flags fields indicating dirty NIFs, a NIF library loading error results. There is no error if a NIF library built with dirty NIF support is loaded into a runtime that does not support dirty NIFs but the library does not have any dirty NIFs. It is also not an error if a library without dirty NIF support is loaded into a runtime built with dirty NIF support. Add documentation and tests for enif_schedule_nif().
2014-03-21Introduce minimum allowed major driver and nif versions on loadRickard Green
2014-01-28initial support for dirty schedulers and dirty NIFsSteve Vinoski
Add initial support for dirty schedulers. There are two types of dirty schedulers: CPU schedulers and I/O schedulers. By default, there are as many dirty CPU schedulers as there are normal schedulers and as many dirty CPU schedulers online as normal schedulers online. There are 10 dirty I/O schedulers (similar to the choice of 10 as the default for async threads). By default, dirty schedulers are disabled and conditionally compiled out. To enable them, you must pass --enable-dirty-schedulers to the top-level configure script when building Erlang/OTP. Current dirty scheduler support requires the emulator to be built with SMP support. This restriction will be lifted in the future. You can specify the number of dirty schedulers with the command-line options +SDcpu (for dirty CPU schedulers) and +SDio (for dirty I/O schedulers). The +SDcpu option is similar to the +S option in that it takes two numbers separated by a colon: C1:C2, where C1 specifies the number of dirty schedulers available and C2 specifies the number of dirty schedulers online. The +SDPcpu option allows numbers of dirty CPU schedulers available and dirty CPU schedulers online to be specified as percentages, similar to the existing +SP option for normal schedulers. The number of dirty CPU schedulers created and dirty CPU schedulers online may not exceed the number of normal schedulers created and normal schedulers online, respectively. The +SDio option takes only a single number specifying the number of dirty I/O schedulers available and online. There is no support yet for programmatically changing at run time the number of dirty CPU schedulers online via erlang:system_flag/2. Also, changing the number of normal schedulers online via erlang:system_flag(schedulers_online, NewSchedulersOnline) should ensure that there are no more dirty CPU schedulers than normal schedulers, but this is not yet implemented. You can retrieve the number of dirty schedulers by passing dirty_cpu_schedulers, dirty_cpu_schedulers_online, or dirty_io_schedulers to erlang:system_info/1. Currently only NIFs are able to access dirty scheduler functionality. Neither drivers nor BIFs currently support dirty schedulers. This restriction will be addressed in the future. If dirty scheduler support is present in the runtime, the initial status line Erlang prints before presenting its interactive prompt will include the indicator "[ds:C1:C2:I]" where "ds" indicates "dirty schedulers", "C1" indicates the number of dirty CPU schedulers available, "C2" indicates the number of dirty CPU schedulers online, and "I" indicates the number of dirty I/O schedulers. Document The dirty NIF API in the erl_nif man page. The API closely follows Rickard Green's presentation slides from his talk "Future Extensions to the Native Interface", presented at the 2011 Erlang Factory held in the San Francisco Bay Area. Rickard's slides are available online at http://bit.ly/1m34UHB . Document the new erl command-line options, the additions to erlang:system_info/1, and also add the erlang:system_flag/2 dirty scheduler documentation even though it's not yet implemented. To determine whether the dirty NIF API is available, native code can check to see whether the C preprocessor macro ERL_NIF_DIRTY_SCHEDULER_SUPPORT is defined. To check if dirty schedulers are available at run time, native code can call the boolean enif_have_dirty_schedulers() function, and Erlang code can call erlang:system_info(dirty_cpu_schedulers), which raises badarg if no dirty scheduler support is available. Add a simple dirty NIF test to the emulator NIF suite.
2013-08-21erts: Add option to include nifs staticallyLukas Larsson
Both crypto and asn1 are supported.
2013-04-19Convert XML files to UTF-8Hans Bolinder
2013-02-22Update copyright yearsBjörn-Egil Dahlberg
2013-02-13erts: Add enif_consume_timesliceSverker Eriksson
2012-11-15Add clearer warnings about misuse of NIF and driver functionalityRickard Green
2012-07-11erts: add space before '*' in some function prototypesHans Bolinder
2011-11-29erts: Deprecate the NIF reload mechanismSverker Eriksson
The reload mechanism is an odd feature that does not harmonize with how module upgrade is otherwise done. We do not want its presence to hinder future development of code loading and upgrade.
2011-10-18Merge branch 'fm/enif_is_number'Henrik Nord
* fm/enif_is_number: Add NIF function enif_is_number Conflicts: erts/emulator/beam/erl_nif_api_funcs.h OTP-9629
2011-09-20Merge branch 'dev' into majorHenrik Nord
Conflicts: erts/aclocal.m4 erts/include/internal/ethread_header_config.h.in
2011-09-15Fix typos (variable name) in erl_nif(3)Tuncer Ayaz
2011-07-01Rename enif_get_reverse_list to enif_make_reverse_listLukas Larsson
2011-06-30Added enif_get_reverse_list to nif APILukas Larsson
2011-06-08Add NIF function enif_is_numberFilipe David Manana
This function allows for easily determining if a term represents or not a number (integer, float, small or big).
2011-03-24add support for checking if an ERL_NIF_TERM is an exceptionSteve Vinoski
Add the enif_is_exception function to allow callers to determine whether an ERL_NIF_TERM represents an exception. (Currently the only supported exception is badarg since only enif_make_badarg exists, but this will likely be expanded in future releases.) This allows NIF code to call other NIF functions that return ERL_NIF_TERM and properly check to see if the returned terms are exceptions. Without the enif_is_exception function, developers have to create their own means of checking whether a function creates an exception, such as returning boolean success/failure indicators or some other special value indicating that an exception is in effect. The declaration of enif_is_exception in erl_nif_api_funcs.h respects the order of declarations required to keep compatibility on Windows. Add a new test to verify the operation of enif_is_exception. Modify the erl_nif man page to add a description of enif_is_exception and also to clarify the requirements of calling the enif_make_badarg function. If code calls enif_make_badarg, the env passed in gets set with exception information and so the return value of the calling function MUST be the badarg term returned from enif_make_badarg. Also clarify that the result of enif_make_badarg may be passed only to enif_is_exception and not to any other NIF API functions.
2011-03-09clarify NIF resource object deallocation documentationSteve Vinoski
In the erl_nif documentation, clarify how and when NIF resource objects can be deallocated. Specifically, add focus for the case of calling enif_release_resource immediately after obtaining a resource term from enif_make_resource, since this is likely to be a common approach NIFs use to manage resources. Also fix a couple misspellings in the erl_nif documentation.
2011-01-05Fix minor typos in erl_nif documentationSverker Eriksson
enif_realloc_binary return int enif_alloc/enif_free does not accept env as first argument. enif_send return int enif_self in alphabetic order
2010-09-06Remove warning about experimental status of NIFs from erlang.xmlPatrik Nyblom
Also made the SEEALSO link at the bottom of erl_nif.xml more "erlangish".
2010-07-23NIF doc official support noteSverker Eriksson
2010-07-23NIF 64-bit integer supportSverker Eriksson
2010-06-03OTP-8555 Send message from NIFSverker Eriksson
New NIF features: Send messages from a NIF, or from thread created by NIF, to any local process (enif_send) Store terms between NIF calls (enif_alloc_env, enif_make_copy) Create binary terms with user defined memory management (enif_make_resource_binary)
2010-05-24erl_nif: add make_atom_len, make_existing_atom_len and make_string_lenTuncer Ayaz
Add new NIF API functions - enif_make_atom_len - enif_make_existing_atom_len - enif_make_string_len These are basically the same as enif_make_atom, enif_make_existing_atom and enif_make_string except that the new functions require a length parameter instead of a null-terminated C-string. Signed-off-by: Tuncer Ayaz <[email protected]>
2010-05-24erl_nif: add enif_get_atom_length and enif_get_list_lengthTuncer Ayaz
Add new NIF API functions - enif_get_atom_length - enif_get_list_length Signed-off-by: Tuncer Ayaz <[email protected]>
2010-05-24erl_nif: add enif_is_list and enif_is_tupleTuncer Ayaz
Add new NIF API functions - enif_is_list - enif_is_tuple Signed-off-by: Tuncer Ayaz <[email protected]>
2010-04-28OTP-8474 NIF improvements after R13B04Sverker Eriksson
New NIF API function enif_make_new_binary
2010-04-07Fix typos in erl_nif.xmlTuncer Ayaz
Fix a couple trivial typos in erl_nif.xml. Signed-off-by: Tuncer Ayaz <[email protected]>
2010-02-17OTP-8335 NIF improvements:Sverker Eriksson
Driver API for multi-threading made available for NIFs. Support for mempory managed (garbage collected) resource objects. A way to pass "pointers" to native data structures between C and Erlang in a safe way. Support for references, floats and term comparison. Various new functions, like enif_inspect_iolist_as_binary, enif_make_sub_binary, enif_get_string, enif_get_atom, enif_make_tuple_from_array, enif_make_list_from_array, enif_make_existing_atom.
2010-02-17OTP-8335 NIF improvements:Sverker Eriksson
Driver API for multi-threading made available for NIFs. Support for mempory managed (garbage collected) resource objects. A way to pass "pointers" to native data structures between C and Erlang in a safe way. Support for references, floats and term comparison. Various new functions, like enif_inspect_iolist_as_binary, enif_make_sub_binary, enif_get_string, enif_get_atom, enif_make_tuple_from_array, enif_make_list_from_array, enif_make_existing_atom.
2010-02-15OTP-8335 NIF improvements:Sverker Eriksson
Driver API for multi-threading made available for NIFs. Support for mempory managed (garbage collected) resource objects. A way to pass "pointers" to native data structures between C and Erlang in a safe way. Various new functions, like enif_inspect_iolist_as_binary, enif_make_sub_binary, enif_get_string, enif_get_atom, enif_make_tuple_from_array, enif_make_list_from_array, enif_make_existing_atom.
2010-02-11OTP-8335 Even more NIF featuresSverker Eriksson
2010-01-26OTP-8343 The documentation is now possible to build in an open sourceLars G Thorsen
environment after a number of bugs are fixed and some features are added in the documentation build process. - The arity calculation is updated. - The module prefix used in the function names for bif's are removed in the generated links so the links will look like http://www.erlang.org/doc/man/erlang.html#append_element-2 instead of http://www.erlang.org/doc/man/erlang.html#erlang:append_element-2 - Enhanced the menu positioning in the html documentation when a new page is loaded. - A number of corrections in the generation of man pages (thanks to Sergei Golovan) - Moved some man pages to more apropriate sections, pages in section 4 moved to 5 and pages in 6 moved to 7. - The legal notice is taken from the xml book file so OTP's build process can be used for non OTP applications.
2009-12-09OTP-8304 Incompatible changes in the experimental NIF feature. Changed theSverker Eriksson
NIF function prototypes in order to allow more than 3 function arguments. Also an incompatible change in the return value of erlang:load_nif/2. Added support for references, floats and term comparison in NIFs. Read more in the documentation of erl_nif and erlang:load_nif/2.