Add finalize_cb to jerry_context_data_manager_t (#2269)

This patch adds a new finalize_cb callback to jerry_context_data_manager_t.
The callback is run as the very last thing in jerry_cleanup, after the VM has been torn down entirely.
There was already the deinit_cb, which is run while the VM is still in the process of being torn down.
The reason the deinit_cb is not always sufficient is that there may still be objects alive (because they still being referenced) that have native pointers associated with the context manager that is being deinit'ed.
As a result, the free_cb's for those objects can get called *after* the associated context manager's deinit_cb is run. This makes cleanup of manager state that is depended on by the live objects impossible to do in the deinit_cb. That type of cleanup can only be done when all values have been torn down completely.

JerryScript-DCO-1.0-Signed-off-by: Martijn The martijn.the@intel.com

1 files changed, 41 insertions, 5 deletions

diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md
index a04b9602..8ca2c622 100644
--- a/docs/02.API-REFERENCE.md
+++ b/docs/02.API-REFERENCE.md
@@ -128,17 +128,53 @@ typedef uint32_t jerry_value_t;
 
 Structure that defines how a context data item will be initialized and deinitialized. JerryScript zeroes out the memory
 for the item by default, and if the `init_cb` field is not NULL, it will be called with the pointer to the memory as
-an additional custom initializer. The `deinit_cb` (if non-`NULL`) is called during a call to `jerry_cleanup()` to run
-any custom deinitialization.
+an additional custom initializer. The `deinit_cb` (if non-`NULL`) is called during a call to `jerry_cleanup ()` to run
+any custom deinitialization *before* the VM has been fully cleaned up. The `finalize_cb` (if non-`NULL`) is also called
+during a call to `jerry_cleanup ()` to run any custom deinitialization *after* the VM has been fully cleaned up.
 
 **Prototype**
 
 ```c
 typedef struct
 {
-  void (*init_cb) (void *); /**< callback responsible for initializing a context item, or NULL */
-  void (*deinit_cb) (void *); /**< callback responsible for deinitializing a context item, or NULL */
-  size_t bytes_needed; /**< number of bytes to allocate for this manager */
+  /**
+   * Callback responsible for initializing a context item, or NULL to zero out the memory. This is called lazily, the
+   * first time jerry_get_context_data () is called with this manager.
+   *
+   * @param [in] data The buffer that JerryScript allocated for the manager. The buffer is zeroed out. The size is
+   * determined by the bytes_needed field. The buffer is kept alive until jerry_cleanup () is called.
+   */
+  void (*init_cb) (void *data);
+
+  /**
+   * Callback responsible for deinitializing a context item, or NULL. This is called as part of jerry_cleanup (),
+   * right *before* the VM has been cleaned up. This is a good place to release strong references to jerry_value_t's
+   * that the manager may be holding.
+   * Note: because the VM has not been fully cleaned up yet, jerry_object_native_info_t free_cb's can still get called
+   * *after* all deinit_cb's have been run. See finalize_cb for a callback that is guaranteed to run *after* all
+   * free_cb's have been run.
+   *
+   * @param [in] data The buffer that JerryScript allocated for the manager.
+   */
+  void (*deinit_cb) (void *data);
+
+  /**
+   * Callback responsible for finalizing a context item, or NULL. This is called as part of jerry_cleanup (),
+   * right *after* the VM has been cleaned up and destroyed and jerry_... APIs cannot be called any more. At this point,
+   * all values in the VM have been cleaned up. This is a good place to clean up native state that can only be cleaned
+   * up at the very end when there are no more VM values around that may need to access that state.
+   *
+   * @param [in] data The buffer that JerryScript allocated for the manager. After returning from this callback,
+   * the data pointer may no longer be used.
+   */
+  void (*finalize_cb) (void *data);
+
+  /**
+   * Number of bytes to allocate for this manager. This is the size of the buffer that JerryScript will allocate on
+   * behalf of the manager. The pointer to this buffer is passed into init_cb, deinit_cb and finalize_cb. It is also
+   * returned from the jerry_get_context_data () API.
+   */
+  size_t bytes_needed;
 } jerry_context_data_manager_t;
 ```