1 /* 2 * Copyright (C) 2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef NODEJSTASKQUEUE_H 17 #define NODEJSTASKQUEUE_H 18 #include <meta/interface/intf_task_queue.h> 19 20 #include "napi_api.h" 21 22 /* 23 * NodeJSTaskQueue identifier 24 */ 25 static constexpr BASE_NS::Uid JS_THREAD_DEP { "b2e8cef3-453a-4651-b564-5190f8b5190d" }; 26 27 /* 28 * NodeJSTaskQueue executes it's tasks in the thread where it was first initialized, which MUST have a valid napi_env. 29 * napi_env must be passed to the instance in a "Create" parameter block, in a parameter "env" of type "uintptr_t" 30 * 31 * See INodeJSTaskQueue for more information. 32 */ 33 META_REGISTER_CLASS(NodeJSTaskQueue, "66aabbba-ec01-47f8-ac68-2393cfc76a9a", META_NS::ObjectCategoryBits::NO_CATEGORY) 34 35 /* 36 * INodeJSTaskQueue can be used by tasks in NodeJSTaskQueue to access the napi_env where the tasks run. 37 * 38 * "GetNapiEnv" result is only valid in the thread where it was created. 39 * "Acquire" MUST be called on the creating thread. 40 * "Release" MUST be called on the creating thread. 41 * 42 * Before the task queue can schedule/run tasks, the queue must be "acquired". 43 * 44 * Acquire must be called atleast once in the creating thread. 45 * Release must be called as many times as Acquire is done. 46 * 47 * after first acquired, the NodeJS message loop will be kept alive. 48 * after fully released, then AFTER all tasks in queue have run to completion, the javascript side resources are 49 * released, allowing NodeJS to terminate. 50 * 51 * while being fully released, the addtask methods will fail. 52 * requiring a new acquire to work again. 53 * 54 * NodeJSQueue is created and acquired by the SceneJS and released by SceneJS. 55 */ 56 class INodeJSTaskQueue : public CORE_NS::IInterface { 57 META_INTERFACE(CORE_NS::IInterface, INodeJSTaskQueue, "9d898eee-f592-410b-bf72-c8baeaa65614"); 58 59 public: 60 // provides access to the environment. 61 // this is provided so tasks can do napi calls. 62 // ONLY safe to use while executing tasks INodeJSTaskQueue (or the thread where napi_env is created) 63 virtual napi_env GetNapiEnv() const = 0; 64 65 // These are safe in the napi_env / js thread. 66 67 // The following are counted. 68 // When released to 0, the queue will run to termination, and release JS resources 69 // Acquire can be used to allocate the said resources again. 70 71 // Acquire makes sure that the queue can work 72 virtual bool Acquire() = 0; 73 // Release allows the resources to be released 74 virtual bool Release() = 0; 75 76 // Returns if it's safe to destroy the instance. (fully released with no tasks) 77 virtual bool IsReleased() = 0; 78 }; 79 80 // creates and registers the main nodetaskqueue instance if it doesn't exist yet. (uses provided napi_env) 81 // MUST BE CALLED IN THE THREAD OWNING THE NAPI_ENV! 82 META_NS::ITaskQueue::Ptr GetOrCreateNodeTaskQueue(napi_env e); 83 84 // unregisters the main nodetaskqueue instance. 85 // this SHOULD be called after no users left. 86 // and the queue being fully "Released". 87 // MUST BE CALLED IN THE THREAD OWNING THE NAPI_ENV! 88 bool DeinitNodeTaskQueue(); 89 #endif 90