Advertisement
robertbira

Italian Translation Report: Node.js [Part 13 - 1783 words]

Jul 25th, 2018
181
0
Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
text 10.89 KB | None | 0 0
  1. Function pointer type for add-on provided functions that allow the user to be notified when externally-owned data is ready to be cleaned up because the object with which it was associated with, has been garbage-collected.
  2. The user must provide a function satisfying the following signature which would get called upon the object's collection.
  3. Currently, can be used for finding out when objects that have external data are collected.
  4. In some cases it is useful to be able to get more detailed information, including a string representing the error as well as VM (engine)-specific information.
  5. Wraps a native instance in a JavaScript object.
  6. The native instance can be retrieved later using
  7. When JavaScript code invokes a constructor for a class that was defined using, the for the constructor is invoked.
  8. After constructing an instance of the native class, the callback must then call to wrap the newly constructed instance in the already-created JavaScript object that is the argument to the constructor callback.
  9. (That object was created from the constructor function's, so it already has definitions of all the instance properties and methods.)
  10. Typically when wrapping a class instance, a finalize callback should be provided that simply deletes the native instance that is received as the argument to the finalize callback.
  11. The optional returned reference is initially a weak reference, meaning it has a reference count of 0.
  12. Typically this reference count would be incremented temporarily during async operations that require the instance to remain valid.
  13. CAUTION: The optional returned reference (if obtained) should be deleted via ONLY in response to the finalize callback invocation.
  14. (If it is deleted before then, then the finalize callback may never be invoked.) Therefore, when obtaining a reference a finalize callback is also required in order to enable correct proper of the reference.
  15. This API may modify the prototype chain of the wrapper object.
  16. Afterward, additional manipulation of the wrapper's prototype chain may cause to fail.
  17. Calling a second time on an object will return an error.
  18. To associate another native instance with the object, use first.
  19. The object associated with the native instance.
  20. Pointer to the wrapped native instance.
  21. Retrieves a native instance that was previously wrapped in a JavaScript object using
  22. When JavaScript code invokes a method or property accessor on the class, the corresponding is invoked.
  23. If the callback is for an instance method or accessor, then the argument to the callback is the wrapper object; the wrapped C++ instance that is the target of the call can be obtained then by calling on the wrapper object.
  24. Retrieves a native instance that was previously wrapped in the JavaScript object using and removes the wrapping, thereby restoring the JavaScript object's prototype chain.
  25. If a finalize callback was associated with the wrapping, it will no longer be called when the JavaScript object becomes garbage-collected.
  26. Simple Asynchronous Operations
  27. Addon modules often need to leverage async helpers from libuv as part of their implementation. This allows them to schedule work to be executed asynchronously so that their methods can return in advance of the work being completed. This is important in order to allow them to avoid blocking overall execution of the Node.js application.
  28. N-API provides an ABI-stable interface for these supporting functions which covers the most common asynchronous use cases.
  29. N-API defines the napi_work structure which is used to manage asynchronous workers. Instances are created/deleted with and
  30. The and callbacks are functions that will be invoked when the executor is ready to execute and when it completes its task respectively. These functions implement the following interfaces:
  31. When these methods are invoked, the parameter passed will be the addon-provided data that was passed into the call.
  32. Once created the async worker can be queued for execution using the function:
  33. can be used if the work needs to be cancelled before the work has started execution.
  34. After calling, the callback will be invoked with a status value of
  35. The work should not be deleted before the callback invocation, even when it was cancelled.
  36. An optional object associated with the async work that will be passed to possible
  37. Identifier for the kind of resource that is being provided for diagnostic information exposed by the API.
  38. The native function which should be called to execute the logic asynchronously.
  39. The given function is called from a worker pool thread and can execute in parallel with the main event loop thread.
  40. The native function which will be called when the asynchronous logic is completed or is cancelled.
  41. The given function is called from the main event loop thread.
  42. User-provided data context.This will be passed back into the execute and complete functions.
  43. which is the handle to the newly created async work.
  44. This API allocates a work object that is used to execute logic asynchronously.
  45. It should be freed using once the work is no longer required.
  46. should be a null-terminated, UTF-8-encoded string
  47. The identifier is provided by the user and should be representative of the type of async work being performed.
  48. It is also recommended to apply namespacing to the identifier, e.g. by including the module name.
  49. See the for more information.
  50. The handle returned by the call to
  51. This API frees a previously allocated work object.
  52. This API can be called even if there is a pending JavaScript exception.
  53. This API requests that the previously allocated work be scheduled for execution.
  54. This API cancels queued work if it has not yet been started.
  55. If it has already started executing, it cannot be cancelled and will be returned.
  56. Custom Asynchronous Operations
  57. The simple asynchronous work APIs above may not be appropriate for every scenario.
  58. When using any other asynchronous mechanism, the following APIs are necessary to ensure an asynchronous operation is properly tracked by the runtime.
  59. The initialized async context.
  60. The async context to be destroyed.
  61. Context for the async operation that is invoking the callback.
  62. This should normally be a value previously obtained from
  63. However is also allowed, which indicates the current async context (if any) is to be used for the callback.
  64. The object passed to the called function.
  65. representing the JavaScript function to be invoked.
  66. The count of elements in the array.
  67. Array of JavaScript values as representing the arguments to the function.
  68. This API is similar to
  69. However, it is used to call from native code back into JavaScript after returning from an async operation (when there is no other script on the stack).
  70. It is a fairly simple wrapper around
  71. Note it is not necessary to use from within a; in that situation the callback's async context has already been set up, so a direct call to is sufficient and appropriate.
  72. Use of the function may be required when implementing custom async behavior that does not use
  73. The newly created scope.
  74. There are cases (for example resolving promises) where it is necessary to have the equivalent of the scope associated with a callback in place when making certain N-API calls. If there is no other script on the stack the
  75. functions can be used to open/close the required scope.
  76. The scope to be closed.
  77. Version Management
  78. A pointer to version information for Node.js itself.
  79. This function fills the struct with the major, minor, and patch version of Node.js that is currently running, and the field with the
  80. value of
  81. The returned buffer is statically allocated and does not need to be freed.
  82. The highest version of N-API supported.
  83. This API returns the highest N-API version supported by the Node.js runtime. N-API is planned to be additive such that newer releases of Node.js may support additional API functions. In order to allow an addon to use a newer function when running with versions of Node.js that support it, while providing fallback behavior when running with Node.js versions that don't support it:
  84. Call to determine if the API is available.
  85. If available, dynamically load a pointer to the function using
  86. Use the dynamically loaded pointer to invoke the function.
  87. If the function is not available, provide an alternate implementation that does not use the function.
  88. Memory Management
  89. The change in externally allocated memory that is kept alive by JavaScript objects.
  90. The adjusted value
  91. This function gives V8 an indication of the amount of externally allocated memory that is kept alive by JavaScript objects (i.e. a JavaScript object that points to its own memory allocated by a native module). Registering externally allocated memory will trigger global garbage collections more often than it would otherwise.
  92. N-API provides facilities for creating objects as described in
  93. It implements promises as a pair of objects.
  94. When a promise is created by, a "deferred" object is created and returned alongside the
  95. The deferred object is bound to the created and is the only means to resolve or reject the using or
  96. The deferred object that is created by is freed by or
  97. The object may be returned to JavaScript where it can be used in the usual fashion.
  98. For example, to create a promise and pass it to an asynchronous worker:
  99. // Create the promise.
  100. // Pass the deferred to a function that performs an asynchronous action.
  101. // Return the promise to JS
  102. The above function would perform its asynchronous action and then it would resolve or reject the deferred, thereby concluding the promise and freeing the deferred:
  103. // Create a value with which to conclude the deferred.
  104. // Resolve or reject the promise associated with the deferred depending on
  105. // whether the asynchronous action succeeded.
  106. // At this point the deferred has been freed, so we should assign NULL to it.
  107. A newly created deferred object which can later be passed to or to resolve resp. reject the associated promise.
  108. The JavaScript promise associated with the deferred object.
  109. This API creates a deferred object and a JavaScript promise.
  110. The deferred object whose associated promise to resolve.
  111. The value with which to resolve the promise.
  112. This API resolves a JavaScript promise by way of the deferred object with which it is associated. Thus, it can only be used to resolve JavaScript promises for which the corresponding deferred object is available. This effectively means that the promise must have been created using and the deferred object returned from that call must have been retained in order to be passed to this API.
  113. The deferred object is freed upon successful completion.
  114. The promise to examine
  115. Flag indicating whether is a native promise object - that is, a promise object created by the underlying engine.
  116. Script execution
  117. N-API provides an API for executing a string containing JavaScript using the underlying JavaScript engine.
  118. A JavaScript string containing the script to execute.
  119. The value resulting from having executed the script.
  120. N-API provides a function for getting the current event loop associated with a specific
  121. The current libuv loop instance.
Advertisement
Add Comment
Please, Sign In to add comment
Advertisement