Italian Translation Report: Node.js [Part 5 - 1036 words]

The second approach is to try to handle the exception.
There will be cases
where the native code can catch the exception, take the appropriate action,
and then continue.
This is only recommended in specific cases
where it is known that the exception can be safely handled.
In these
cases can be used to get and
clear the exception.
On success, result will contain the handle to
the last JavaScript
If it is determined, after
retrieving the exception, the exception cannot be handled after all
it can be re-thrown it with where error is the
JavaScript object to be thrown. thrown.
The following utility functions are also available in case native code
needs to throw an exception or determine if a is an instance
of a JavaScript object:  and
The following utility functions are also available in case native
code needs to create an object:  and
where result is the that refers to the newly created
JavaScript object.
The Node.js project is adding error codes to all of the errors generated internally. The goal is for applications to use these error codes for all error checking. The associated error messages will remain, but will only be meant to be used for logging and display with the expectation that the message can change without SemVer applying. In order to support this model with N-API, both in internal functionality and for module specific functionality (as its good practice), the and functions take an optional code parameter which is the string for the code to be added to the error object. If the optional parameter is then no code will be associated with the error. If a code is provided, the name associated with the error is also updated to be:
where is the original name associated with the error
and is the code that was provided.
For example if the code
is and a is being created the name will be:
The environment that the API is invoked under.
The JavaScript value to be thrown.
Returns if the API succeeded.
This API throws the JavaScript value provided.
Optional error code to be set on the error.
C string representing the text to be associated with
the error.
This API throws a JavaScript with the text provided.
 The to be checked.
Boolean value that is set to true if represents
an error, false otherwise.
This API queries a to check if it represents an error object.
Optional with the string for the error code to
be associated with the error.
that references a JavaScript  to be
used as the message for the
representing the error created.
returns
The exception if one is pending, otherwise
This API returns true if an exception is pending.
This API can be called even if there is a pending JavaScript exception.
Boolean value that is set to true if an exception is pending.
The error you want to pass to
Trigger an in JavaScript.
Useful if an async
callback throws an exception with no way to recover.
 Fatal Errors
In the event of an unrecoverable error in a native module, a fatal error can be
thrown to immediately terminate the process.
Optional location at which the error occurred.
The length of the location in bytes, or
 if it is null-terminated.
The message associated with the error.
The function call does not return, the process will be terminated.
Object Lifetime management
As N-API calls are made, handles to objects in the heap for the underlying
VM may be returned as
These handles must hold the
objects 'live' until they are no longer required by the native code,
otherwise the objects could be collected before the native code was
finished using them.
As object handles are returned they are associated with a
'scope'.
The lifespan for the default scope is tied to the lifespan of the native method call. The result is that, by default, handles remain valid and the objects associated with these handles will be held live for the lifespan of the native method call.
In many cases, however, it is necessary that the handles remain valid for either a shorter or longer lifespan than that of the native method. The sections which follow describe the N-API functions than can be used to change the handle lifespan from the default.
Making handle lifespan shorter than that of the native method
It is often necessary to make the lifespan of handles shorter than the lifespan of a native method. For example, consider a native method that has a loop which iterates through the elements in a large array:
This would result in a large number of handles being created, consuming substantial resources. In addition, even though the native code could only use the most recent handle, all of the associated objects would also be kept alive since they all share the same scope.
To handle this case, N-API provides the ability to establish a new 'scope' to which newly created handles will be associated. Once those handles are no longer required, the scope can be 'closed' and any handles associated with the scope are invalidated. The methods available to open/close scopes are and
N-API only supports a single nested hierarchy of scopes. There is only one active scope at any time, and all new handles will be associated with that scope while it is active. Scopes must be closed in the reverse order from which they are opened. In addition, all scopes created within a native method must be closed before returning from that method.
Taking the earlier example, adding calls to and would ensure that at most a single handle is valid throughout the execution of the loop:
do something with element
When nesting scopes, there are cases where a handle from an inner scope needs to live beyond the lifespan of that scope. N-API supports an 'escapable scope' in order to support this case. An escapable scope allows one handle to be 'promoted' so that it 'escapes' the current scope and the lifespan of the handle changes from the current scope to that of the outer scope.
The methods available to open/close escapable scopes are and
The request to promote a handle is made through which can only be called once.