Optimization of Cross-Language Invocation

Introduction

In the native implementation of Cocos Creator version 3.6.0, we have made improvements in the native (CPP) code. This mainly involves the implementation of the node tree (Scene, Node), assets (Asset and its subclasses), material system (Material, Pass, ProgramLib), 3D renderer (including Model, SubModel), and 2D renderer (Batch2D, RenderEntity) in CPP. And these functionalities are exposed to the JS through binding techniques.

As known to all, in Cocos Creator 3.x, developers can only use TypeScript (TS) scripts to develop game logic. Although we have implemented more engine code in CPP, developers cannot directly use CPP for game logic development. Therefore, we use the Script Engine Wrapper API (referred to as SE API) to bind and expose the types implemented in the CPP to JS. The interfaces exposed to JS remain consistent with those in the web environment.

The primary benefit of moving core code to the native is that the execution performance of engine code running on native platforms is improved, especially on platforms that do not support JIT compilation (such as iOS). However, before the official release of version 3.6.0, we also faced a series of side effects resulting from the “elevation of the native level”. The main issue was that the number of JSB calls (interactions between JS and CPP languages) increased significantly compared to previous versions. This directly offset the benefits brought by the elevation of the native level and even resulted in poorer performance compared to the previous version(v3.5). This article will introduce some optimization methods to reduce JSB calls. If developers encounter similar issues with excessive JSB calls in their own CPP code, we hope this article can provide some optimization insights.

Shared Memory

For properties in Node that require frequent synchronization, we utilize shared memory between CPP and JS to avoid JSB calls. To facilitate the sharing of CPP memory with JS, we have encapsulated the bindings::NativeMemorySharedToScriptActor helper class.

bindings/utils/BindingUtils.h

  1. namespace cc::bindings {
  3. class NativeMemorySharedToScriptActor final {
  4. public:
  5.     NativeMemorySharedToScriptActor() = default;
  6.     ~NativeMemorySharedToScriptActor();
  8.     void initialize(void *ptr, uint32_t byteLength);
  9.     void destroy();
  11.     inline se::Object *getSharedArrayBufferObject() const { return _sharedArrayBufferObject; }
  13. private:
  14.     se::Object *_sharedArrayBufferObject{nullptr};
  16.     CC_DISALLOW_COPY_MOVE_ASSIGN(NativeMemorySharedToScriptActor)
  17. };
  19. } // namespace cc::bindings

bindings/utils/BindingUtils.h

  1. #include "bindings/utils/BindingUtils.h"
  2. #include "bindings/jswrapper/SeApi.h"
  4. namespace cc::bindings {
  6. NativeMemorySharedToScriptActor::~NativeMemorySharedToScriptActor() {
  7.     destroy();
  8. }
  10. void NativeMemorySharedToScriptActor::initialize(void* ptr, uint32_t byteLength) {
  11.     CC_ASSERT_NULL(_sharedArrayBufferObject);
  12.     // The callback of freeing buffer is empty since the memory is managed in native,
  13.     //The external array buffer just holds a reference to the memory.
  14.     _sharedArrayBufferObject = se::Object::createExternalArrayBufferObject(ptr, byteLength, [](void* /*contents*/, size_t /*byteLength*/, void* /*userData*/) {});
  15.     // Root this object to prevent it from being garbage collected (GC), we will invoke `unroot` in the destroy function.
  16.     _sharedArrayBufferObject->root();
  17. }
  19. void NativeMemorySharedToScriptActor::destroy() {
  20.     if (_sharedArrayBufferObject != nullptr) {
  21.         _sharedArrayBufferObject->unroot();
  22.         _sharedArrayBufferObject->decRef();
  23.         _sharedArrayBufferObject = nullptr;
  24.     }
  25. }
  27. } // namespace cc::bindings

bindings/jswrapper/v8/Object.h

  1. using BufferContentsFreeFunc = void (*)(void *contents, size_t byteLength, void *userData);
  2. static Object *createExternalArrayBufferObject(void *contents, size_t byteLength, BufferContentsFreeFunc freeFunc, void *freeUserData = nullptr);

bindings/jswrapper/v8/Object.cpp

  1. /* static */
  2. Object *Object::createExternalArrayBufferObject(void *contents, size_t byteLength, BufferContentsFreeFunc freeFunc, void *freeUserData /* = nullptr*/) {
  3.     Object *obj = nullptr;
  4.     std::shared_ptr<v8::BackingStore> backingStore = v8::ArrayBuffer::NewBackingStore(contents, byteLength, freeFunc, freeUserData);
  5.     v8::Local<v8::ArrayBuffer> jsobj = v8::ArrayBuffer::New(__isolate, backingStore);
  7.     if (!jsobj.IsEmpty()) {
  8.         obj = Object::_createJSObject(nullptr, jsobj);
  9.     }
  10.     return obj;
  11. }

Analysis of the code above reveals that NativeMemorySharedToScriptActor calls the v8::ArrayBuffer::NewBackingStore and v8::ArrayBuffer::New functions to create an External type of ArrayBuffer. It is named “External” because its memory is not allocated and managed internally by V8. Instead, its memory is entirely managed by the code out of V8. When the ArrayBuffer object is garbage collected, the freeFunc callback function is triggered. In Node, the memory that needs to be shared consists of several contiguous properties in the Node. The creation and release of this memory are entirely handled by CPP Node itself, and the destruction of CPP Node instances is controlled by the GC. Therefore, when NativeMemorySharedToScriptActor::initialize internally calls se::Object::createExternalArrayBufferObject, it passes an empty implementation of the callback function.

Node.h

  1. class Node : public CCObject {
  2.     ......
  3.     inline se::Object *_getSharedArrayBufferObject() const { return _sharedMemoryActor.getSharedArrayBufferObject(); } // NOLINT
  4.     ......
  5.     bindings::NativeMemorySharedToScriptActor _sharedMemoryActor;
  6.     ......
  7.         // Shared memory with JS
  8.     // NOTE: TypeArray created in node.jsb.ts _ctor should have the same memory layout
  9.     uint32_t _eventMask{0};                                             // Uint32: 0
  10.     uint32_t _layer{static_cast<uint32_t>(Layers::LayerList::DEFAULT)}; // Uint32: 1
  11.     uint32_t _transformFlags{0};                                        // Uint32: 2
  12.     index_t _siblingIndex{0};                                           // Int32: 0
  13.     uint8_t _activeInHierarchy{0};                                      // Uint8: 0
  14.     uint8_t _active{1};                                                 // Uint8: 1
  15.     uint8_t _isStatic{0};                                               // Uint8: 2
  16.     uint8_t _padding{0};                                                // Uint8: 3
  17.     ......
  18. };

Node.cpp

  1. Node::Node(const ccstd::string &name) {
  2. #define NODE_SHARED_MEMORY_BYTE_LENGTH (20)
  3.     static_assert(offsetof(Node, _padding) + sizeof(_padding) - offsetof(Node, _eventMask) == NODE_SHARED_MEMORY_BYTE_LENGTH, "Wrong shared memory size");
  4.     _sharedMemoryActor.initialize(&_eventMask, NODE_SHARED_MEMORY_BYTE_LENGTH);
  5. #undef NODE_SHARED_MEMORY_BYTE_LENGTH
  7.     _id = idGenerator.getNewId();
  8.     if (name.empty()) {
  9.         _name.append("New Node");
  10.     } else {
  11.         _name = name;
  12.     }
  13. }

In the Node constructor, _sharedMemoryActor.initialize(&_eventMask, NODE_SHARED_MEMORY_BYTE_LENGTH); is called to set the first 20 bytes starting from the _eventMask property as shared memory.

node.jsb.ts

Note: All files ending with .jsb.ts will be replaced with their corresponding versions without the .jsb extension during the packaging process. For example, node.jsb.ts will replace node.ts. You can refer to the cc.config.json file in the root directory of the engine for more details. It contains the corresponding overrides field, such as "cocos/scene-graph/node.ts": "cocos/scene-graph/node.jsb.ts".

  1. // The _ctor callback function in JS is triggered during the final stage of the `var node = new Node();` process in JS, i.e., after the CPP Node object is created. Therefore, the ArrayBuffer returned by the _getSharedArrayBufferObject binding function must exist.
  2. nodeProto._ctor = function (name?: string) {
  3.     ......
  4.     // Get the CPP shared ArrayBuffer object through the _getSharedArrayBufferObject binding method
  5.     const sharedArrayBuffer = this._getSharedArrayBufferObject();
  6.     // Uint32Array with 3 elements, offset from the start: eventMask, layer, dirtyFlags
  7.     this._sharedUint32Arr = new Uint32Array(sharedArrayBuffer, 0, 3);
  8.     // Int32Array with 1 element, offset from the 12th byte: siblingIndex
  9.     this._sharedInt32Arr = new Int32Array(sharedArrayBuffer, 12, 1);
  10.     // Uint8Array with 3 elements, offset from the 16th byte: activeInHierarchy, active, static
  11.     this._sharedUint8Arr = new Uint8Array(sharedArrayBuffer, 16, 3);
  12.     //
  14.     this._sharedUint32Arr[1] = Layers.Enum.DEFAULT; // this._sharedUint32Arr[1] represents the layer
  15.     ......
  16. };

By using shared memory, it also means that we cannot pass the values to be set from JS to CPP through JSB binding functions. Therefore, we need to define corresponding getter/setter functions in the .jsb.ts file. These functions will internally modify the shared memory by directly manipulating the TypedArray.

  1. Object.defineProperty(nodeProto, 'activeInHierarchy', {
  2.     configurable: true,
  3.     enumerable: true,
  4.     get (): Readonly<Boolean> {
  5.         return this._sharedUint8Arr[0] != 0; // Uint8, 0: activeInHierarchy
  6.     },
  7.     set (v) {
  8.         this._sharedUint8Arr[0] = (v ? 1 : 0); // Uint8, 0: activeInHierarchy
  9.     },
  10. });
  12. Object.defineProperty(nodeProto, '_activeInHierarchy', {
  13.     configurable: true,
  14.     enumerable: true,
  15.     get (): Readonly<Boolean> {
  16.         return this._sharedUint8Arr[0] != 0; // Uint8, 0: activeInHierarchy
  17.     },
  18.     set (v) {
  19.         this._sharedUint8Arr[0] = (v ? 1 : 0); // Uint8, 0: activeInHierarchy
  20.     },
  21. });
  23. Object.defineProperty(nodeProto, 'layer', {
  24.     configurable: true,
  25.     enumerable: true,
  26.     get () {
  27.         return this._sharedUint32Arr[1]; // Uint32, 1: layer
  28.     },
  29.     set (v) {
  30.         this._sharedUint32Arr[1] = v; // Uint32, 1: layer
  31.         if (this._uiProps && this._uiProps.uiComp) {
  32.             this._uiProps.uiComp.setNodeDirty();
  33.             this._uiProps.uiComp.markForUpdateRenderData();
  34.         }
  35.         this.emit(NodeEventType.LAYER_CHANGED, v);
  36.     },
  37. });
  39. Object.defineProperty(nodeProto, '_layer', {
  40.     configurable: true,
  41.     enumerable: true,
  42.     get () {
  43.         return this._sharedUint32Arr[1]; // Uint32, 1: layer
  44.     },
  45.     set (v) {
  46.         this._sharedUint32Arr[1] = v; // Uint32, 1: layer
  47.     },
  48. });
  50. Object.defineProperty(nodeProto, '_eventMask', {
  51.     configurable: true,
  52.     enumerable: true,
  53.     get () {
  54.         return this._sharedUint32Arr[0]; // Uint32, 0: eventMask
  55.     },
  56.     set (v) {
  57.         this._sharedUint32Arr[0] = v; // Uint32, 0: eventMask
  58.     },
  59. });
  61. Object.defineProperty(nodeProto, '_siblingIndex', {
  62.     configurable: true,
  63.     enumerable: true,
  64.     get () {
  65.         return this._sharedInt32Arr[0]; // Int32, 0: siblingIndex
  66.     },
  67.     set (v) {
  68.         this._sharedInt32Arr[0] = v; // Int32, 0: siblingIndex
  69.     },
  70. });
  72. nodeProto.getSiblingIndex = function getSiblingIndex() {
  73.     return this._sharedInt32Arr[0]; // Int32, 0: siblingIndex
  74. };
  76. Object.defineProperty(nodeProto, '_transformFlags', {
  77.     configurable: true,
  78.     enumerable: true,
  79.     get () {
  80.         return this._sharedUint32Arr[2]; // Uint32, 2: _transformFlags
  81.     },
  82.     set (v) {
  83.         this._sharedUint32Arr[2] = v; // Uint32, 2: _transformFlags
  84.     },
  85. });
  87. Object.defineProperty(nodeProto, '_active', {
  88.     configurable: true,
  89.     enumerable: true,
  90.     get (): Readonly<Boolean> {
  91.         return this._sharedUint8Arr[1] != 0; // Uint8, 1: active
  92.     },
  93.     set (v) {
  94.         this._sharedUint8Arr[1] = (v ? 1 : 0); // Uint8, 1: active
  95.     },
  96. });
  98. Object.defineProperty(nodeProto, 'active', {
  99.     configurable: true,
  100.     enumerable: true,
  101.     get (): Readonly<Boolean> {
  102.         return this._sharedUint8Arr[1] != 0; // Uint8, 1: active
  103.     },
  104.     set (v) {
  105.         this.setActive(!!v);
  106.     },
  107. });
  109. Object.defineProperty(nodeProto, '_static', {
  110.     configurable: true,
  111.     enumerable: true,
  112.     get (): Readonly<Boolean> {
  113.         return this._sharedUint8Arr[2] != 0;
  114.     },
  115.     set (v) {
  116.         this._sharedUint8Arr[2] = (v ? 1 : 0);
  117.     },
  118. });

Performance Comparison Results

jsb/opt-1.jpg

Avoiding Parameters Passing

If JSB function calls involve parameters, V8 internally needs to validate the reasonableness of the parameters. These validation tasks can also impact the performance of the calls. For JSB functions that may be frequently called in Node, we avoid passing floating-point parameters by reusing a global Float32Array.

scene-graph/utils.jsb.ts

  1. import { IMat4Like, Mat4 } from '../core/math';
  3. declare const jsb: any;
  5. // For optimizing getPosition, getRotation, getScale
  6. export const _tempFloatArray = new Float32Array(jsb.createExternalArrayBuffer(20 * 4));
  8. export const fillMat4WithTempFloatArray = function fillMat4WithTempFloatArray (out: IMat4Like) {
  9.     Mat4.set(out,
  10.         _tempFloatArray[0], _tempFloatArray[1], _tempFloatArray[2], _tempFloatArray[3],
  11.         _tempFloatArray[4], _tempFloatArray[5], _tempFloatArray[6], _tempFloatArray[7],
  12.         _tempFloatArray[8], _tempFloatArray[9], _tempFloatArray[10], _tempFloatArray[11],
  13.         _tempFloatArray[12], _tempFloatArray[13], _tempFloatArray[14], _tempFloatArray[15]
  14.     );
  15. };
  16. //

The above code defines a global _tempFloatArray that is used to store number or composite types (such as Vec3, Vec4, Mat4, etc.) parameters.

node.jsb.ts

  1. // ......
  2. // Set the FloatArray to the CPP code
  3. Node._setTempFloatArray(_tempFloatArray.buffer); 
  4. // ......
  5. // Reimplement the setPosition function in JS with parameters
  6. nodeProto.setPosition = function setPosition(val: Readonly<Vec3> | number, y?: number, z?: number) {
  7.     if (y === undefined && z === undefined) {
  8.         // When both y and z are undefined, it means the first parameter is of type Vec3
  9.         _tempFloatArray[0] = 3;
  10.         const pos = val as Vec3;
  11.         // Assign the new pos to the FloatArray and this._lpos cache
  12.         this._lpos.x = _tempFloatArray[1] = pos.x;
  13.         this._lpos.y = _tempFloatArray[2] = pos.y;
  14.         this._lpos.z = _tempFloatArray[3] = pos.z;
  15.     } else if (z === undefined) {
  16.         // If z is undefined, there are only 2 parameters x and y
  17.         _tempFloatArray[0] = 2;
  18.         this._lpos.x = _tempFloatArray[1] = val as number;
  19.         this._lpos.y = _tempFloatArray[2] = y as number;
  20.     } else {
  21.         _tempFloatArray[0] = 3;
  22.         this._lpos.x = _tempFloatArray[1] = val as number;
  23.         this._lpos.y = _tempFloatArray[2] = y as number;
  24.         this._lpos.z = _tempFloatArray[3] = z as number;
  25.     }
  26.     this._setPosition(); // This is a native binding function without parameters
  27. };

jsb_scene_manual.cpp

  1. namespace {
  3. /**
  4.  * Helper class for operating on the shared global FloatArray
  5.  */
  6. class TempFloatArray final {
  7. public:
  8.     TempFloatArray() = default;
  9.     ~TempFloatArray() = default;
  11.     inline void setData(float* data) { _data = data; }
  13.     ......
  15.     inline const float& operator[](size_t index) const { return _data[index]; }
  16.     inline float& operator[](size_t index) { return _data[index]; }
  18. private:
  19.     float* _data{ nullptr };
  21.     CC_DISALLOW_ASSIGN(TempFloatArray)
  22. };
  24. TempFloatArray tempFloatArray;
  26. } // namespace
  1. static bool js_scene_Node_setTempFloatArray(se::State& s) // NOLINT(readability-identifier-naming)
  2. {
  3.     const auto& args = s.args();
  4.     size_t argc = args.size();
  5.     CC_UNUSED bool ok = true;
  6.     if (argc == 1) {
  7.         uint8_t* buffer = nullptr;
  8.         args[0].toObject()->getArrayBufferData(&buffer, nullptr);
  9.         // Initialize the associated data of TempFloatArray
  10.         tempFloatArray.setData(reinterpret_cast<float*>(buffer));
  11.         return true;
  12.     }
  13.     SE_REPORT_ERROR("wrong number of arguments: %d, was expecting %d", (int)argc, 1);
  14.     return false;
  15. }
  16. SE_BIND_FUNC(js_scene_Node_setTempFloatArray)
  1. bool register_all_scene_manual(se::Object* obj) // NOLINT(readability-identifier-naming)
  2. {
  3.     ......
  4.     __jsb_cc_Node_proto->defineFunction("_setPosition", _SE(js_scene_Node_setPosition));
  5.     __jsb_cc_Node_proto->defineFunction("_setScale", _SE(js_scene_Node_setScale));
  6.     __jsb_cc_Node_proto->defineFunction("_setRotation", _SE(js_scene_Node_setRotation));
  7.     __jsb_cc_Node_proto->defineFunction("_setRotationFromEuler", _SE(js_scene_Node_setRotationFromEuler));
  8.     __jsb_cc_Node_proto->defineFunction("_rotateForJS", _SE(js_scene_Node_rotateForJS));
  9.     ......
  10. }
  1. // Binding for node._setPosition() without parameters
  2. static bool js_scene_Node_setPosition(void* s) // NOLINT(readability-identifier-naming)
  3. {
  4.     auto* cobj = reinterpret_cast<cc::Node*>(s);
  5.     auto argc = static_cast<size_t>(tempFloatArray[0]);
  6.     if (argc == 2) {
  7.         // Get the parameters from tempFloatArray
  8.         cobj->setPositionInternal(tempFloatArray[1], tempFloatArray[2], true);
  9.     } else {
  10.         cobj->setPositionInternal(tempFloatArray[1], tempFloatArray[2], tempFloatArray[3], true);
  11.     }
  12.     return true;
  13. }
  14. SE_BIND_FUNC_FAST(js_scene_Node_setPosition) // Note that the new SE_BIND_FUNC_FAST macro is used here

Node.h

  1.     inline void setPositionInternal(float x, float y, bool calledFromJS) { setPositionInternal(x, y, _localPosition.z, calledFromJS); }
  2.     void setPositionInternal(float x, float y, float z, bool calledFromJS);

bindings/jswrapper/v8/HelperMacros.h

  1. #define SE_BIND_FUNC(funcName)                                                    \
  2.     void funcName##Registry(const v8::FunctionCallbackInfo<v8::Value> &_v8args) { \
  3.         JsbInvokeScope(#funcName);                                                \
  4.         jsbFunctionWrapper(_v8args, funcName, #funcName);                         \
  5.     }
  7. #define SE_BIND_FUNC_FAST(funcName) \
  8.     void funcName##Registry(const v8::FunctionCallbackInfo<v8::Value> &_v8args) { \
  9.         auto *thisObject = static_cast<se::Object *>(_v8args.This()->GetAlignedPointerFromInternalField(0)); \
  10.         auto *nativeObject = thisObject != nullptr ? thisObject->getPrivateData() : nullptr; \
  11.         funcName(nativeObject); \
  12.     }

bindings/jswrapper/v8/HelperMacros.cpp

  1. // The SE_BIND_FUNC macro calls the jsbFunctionWrapper function, which performs additional tasks internally.
  2. SE_HOT void jsbFunctionWrapper(const v8::FunctionCallbackInfo<v8::Value> &v8args, se_function_ptr func, const char *funcName) {
  3.     bool ret = false;
  4.     v8::Isolate *isolate = v8args.GetIsolate();
  5.     v8::HandleScope scope(isolate);
  6.     bool needDeleteValueArray{false};
  7.     se::ValueArray &args = se::gValueArrayPool.get(v8args.Length(), needDeleteValueArray);
  8.     se::CallbackDepthGuard depthGuard{args, se::gValueArrayPool._depth, needDeleteValueArray};
  9.     se::internal::jsToSeArgs(v8args, args);
  10.     se::Object *thisObject = se::internal::getPrivate(isolate, v8args.This());
  11.     se::State state(thisObject, args);
  12.     ret = func(state);
  13.     if (!ret) {
  14.         SE_LOGE("[ERROR] Failed to invoke %s\n", funcName);
  15.     }
  16.     se::internal::setReturnValue(state.rval(), v8args);
  17. }

The internal implementation of the SE_BIND_FUNC_FAST macro is extremely fast because it is very simple. It immediately triggers the callback function once it obtains the private data, without any se-related API calls. This avoids the conversion between se::Value and jsvalue and also bypasses parameter validation by V8. You can compare it with the standard implementation of the SE_BIND_FUNC macro.

Furthermore, you may wonder why we don’t share the position, rotation, and scale information directly through the approach described in the ‘Shared Memory’ section, but using _setPosition(), _setRotation(), and _setScale() JSB methods without parameters. The reason is that this JSB calls cannot be removed. Let’s take a look at the implementation of Node::setPosition():

  1. class Node : public CCObject {
  2.     ......
  3.     inline void setPosition(const Vec3 &pos) { setPosition(pos.x, pos.y, pos.z); }
  4.     inline void setPosition(float x, float y) { setPosition(x, y, _localPosition.z); }
  5.     inline void setPosition(float x, float y, float z) { setPositionInternal(x, y, z, false); }
  6.     inline void setPositionInternal(float x, float y, bool calledFromJS) { setPositionInternal(x, y, _localPosition.z, calledFromJS); }
  7.     void setPositionInternal(float x, float y, float z, bool calledFromJS);
  9.     ......
  10.     inline uint32_t getChangedFlags() const {
  11.         return _hasChangedFlagsVersion == globalFlagChangeVersion ? _hasChangedFlags : 0;
  12.     }
  13.     inline void setChangedFlags(uint32_t value) {
  14.         _hasChangedFlagsVersion = globalFlagChangeVersion;
  15.         _hasChangedFlags = value;
  16.     }
  17.     ......
  18. };
  1. void Node::setPositionInternal(float x, float y, float z, bool calledFromJS) {
  2.     _localPosition.set(x, y, z);
  3.     invalidateChildren(TransformBit::POSITION);
  5.     if (_eventMask & TRANSFORM_ON) {
  6.         emit<TransformChanged>(TransformBit::POSITION);
  7.     }
  9.     if (!calledFromJS) {
  10.         notifyLocalPositionUpdated();
  11.     }
  12. }

setPosition not only assigns a value to _localPosition, but it also needs to trigger the invocation of the invalidateChildren function. invalidateChildren is a recursive function that internally traverses all child nodes and modifies other properties such as _transformFlags, _hasChangedFlagsVersion, and _hasChangedFlags. Therefore, we cannot remove setPosition through the “shared memory” approach mentioned in the first section.

Performance Comparison Results

opt-2.jpg

Caching Properties

Caching properties in the JS can help avoid accessing the C++ interface through getters and reduce JSB(JavaScript Bindings) calls.

node.jsb.ts

  1. Object.defineProperty(nodeProto, 'position', {
  2.     configurable: true,
  3.     enumerable: true,
  4.     get (): Readonly<Vec3> {
  5.         return this._lpos;
  6.     },
  7.     set (v: Readonly<Vec3>) {
  8.         this.setPosition(v as Vec3);
  9.     },
  10. });
  12. nodeProto.getPosition = function getPosition (out?: Vec3): Vec3 {
  13.     if (out) {
  14.         return Vec3.set(out, this._lpos.x, this._lpos.y, this._lpos.z);
  15.     }
  16.     return Vec3.copy(new Vec3(), this._lpos);
  17. };
  19. nodeProto._ctor = function (name?: string) {
  20.     ......
  21.     this._lpos = new Vec3();
  22.     this._lrot = new Quat();
  23.     this._lscale = new Vec3(1, 1, 1);
  24.     this._euler = new Vec3();
  25.     .......
  26. };

Performance Comparison Results

opt-3.jpg

Node Synchronization

In the user’s logic code, it is common to use the following pattern:

  1. const children = node.children;
  2. for (let i = 0; i < children.length; ++i) {
  3.   const child = children[i];
  4.   // do something with child
  5. }

The .children getter may be called frequently, which can result in excessive JSB (JavaScript Bindings) calls. The getter for children is bound uniquely because it represents a JS array, while in CPP it corresponds to the type ccstd::vector<Node*> _children;. As a result, there is no straightforward way to synchronize data between JS Array and CPP’s std::vector. If the .children getter is called using JSB each time, it will generate a temporary JS Array using se::Object::createArrayObject, and then convert each CPP child to JS child using nativevalue_to_se and assign it to the JS Array. This incurs a heavy conversion overhead and generates temporary arrays that need to be garbage collected, adding additional pressure to the GC.

To address this issue, we cache the _children property in the JS. When _children is modified in the CPP, we use the event system to notify the JS code’s _children to update its content. This is achieved by listening to ChildAdded and ChildRemoved events.

Let’s illustrate this with the example of node.addChild(child);:

  1. class Node : public CCObject {
  2.     ......
  3.     inline void addChild(Node *node) { node->setParent(this); }
  5.     inline void removeChild(Node *node) const {
  6.         auto idx = getIdxOfChild(_children, node);
  7.         if (idx != -1) {
  8.             node->setParent(nullptr);
  9.         }
  10.     }
  11.     inline void removeFromParent() {
  12.         if (_parent) {
  13.             _parent->removeChild(this);
  14.         }
  15.     }
  16.     void removeAllChildren();
  17.     ......
  18. };
  1. void Node::setParent(Node* parent, bool isKeepWorld /* = false */) {
  2.     ......
  3.     onSetParent(oldParent, isKeepWorld);
  4.     emit<ParentChanged>(oldParent);
  5.     if (oldParent) {
  6.         if (!(oldParent->_objFlags & Flags::DESTROYING)) {
  7.             index_t removeAt = getIdxOfChild(oldParent->_children, this);
  8.             if (removeAt < 0) {
  9.                 return;
  10.             }
  11.             // Remove the child from the old parent node
  12.             oldParent->_children.erase(oldParent->_children.begin() + removeAt);
  13.             oldParent->updateSiblingIndex();
  14.             oldParent->emit<ChildRemoved>(this);
  15.         }
  16.     }
  17.     if (newParent) {
  18.         ......
  19.         // Add the child to the new parent node
  20.         newParent->_children.emplace_back(this);
  21.         _siblingIndex = static_cast<index_t>(newParent->_children.size() - 1);
  22.         newParent->emit<ChildAdded>(this);
  23.     }
  24.     onHierarchyChanged(oldParent);
  25. }

After calling addChild, the Node::_children in the CPP is modified, it triggers the emit<ChildAdded> event. This event is listened to during Node initialization, as seen in the code snippet in jsb_scene_manual.cpp.

  1. // jsb_scene_manual.cpp
  2. static void registerOnChildAdded(cc::Node *node, se::Object *jsObject) {
  3.     node->on<cc::Node::ChildAdded>(
  4.         [jsObject](cc::Node * /*emitter*/, cc::Node *child) {
  5.             se::AutoHandleScope hs;
  6.             se::Value arg0;
  7.             nativevalue_to_se(child, arg0);
  8.             // Call the private JS function _onChildAdded
  9.             se::ScriptEngine::getInstance()->callFunction(jsObject, "_onChildAdded", 1, &arg0);
  10.         });
  11. }
  13. static bool js_scene_Node_registerOnChildAdded(se::State &s) // NOLINT(readability-identifier-naming)
  14. {
  15.     auto *cobj = SE_THIS_OBJECT<cc::Node>(s);
  16.     SE_PRECONDITION2(cobj, false, "Invalid Native Object");
  18.     auto *jsObject = s.thisObject();
  20.     registerOnChildAdded(cobj, jsObject);
  21.     return true;
  22. }
  23. SE_BIND_FUNC(js_scene_Node_registerOnChildAdded) // NOLINT(readability-identifier-naming)
  25. bool register_all_scene_manual(se::Object *obj) // NOLINT(readability-identifier-naming)
  26. {
  27.     ......
  28.     __jsb_cc_Node_proto->defineFunction("_registerOnChildAdded", _SE(js_scene_Node_registerOnChildAdded));
  29.     ......
  30. }

node.jsb.ts

  1. Object.defineProperty(nodeProto, 'children', {
  2.     configurable: true,
  3.     enumerable: true,
  4.     get () {
  5.         return this._children;
  6.     },
  7.     set (v) {
  8.         this._children = v;
  9.     },
  10. });
  12. nodeProto._onChildRemoved = function (child) {
  13.     this.emit(NodeEventType.CHILD_REMOVED, child);
  14. };
  16. // This function is called by the CPP's registerOnChildAdded function
  17. nodeProto._onChildAdded = function (child) {
  18.     this.emit(NodeEventType.CHILD_ADDED, child);
  19. };
  21. nodeProto.on = function (type, callback, target, useCapture: any = false) {
  22.     switch (type) {
  23.         ......
  24.         case NodeEventType.CHILD_ADDED:
  25.             if (!(this._registeredNodeEventTypeMask & REGISTERED_EVENT_MASK_CHILD_ADDED_CHANGED)) {
  26.                 this._registerOnChildAdded(); // Call the JSB method to register the listener
  27.                 this._registeredNodeEventTypeMask |= REGISTERED_EVENT_MASK_CHILD_ADDED_CHANGED;
  28.             }
  29.             break;
  30.         ......
  31.         default:
  32.             break;
  33.     }
  34.     this._eventProcessor.on(type, callback, target, useCapture);
  35. };
  37. nodeProto._ctor = function (name?: string) {
  38.     ......
  39.     this._children = [];
  41.       // Use the on interface to listen for CHILD_ADDED and CHILD_REMOVED events
  42.     this.on(NodeEventType.CHILD_ADDED, (child) => {
  43.         // Synchronize the this._children array in the JS
  44.         this._children.push(child);
  45.     });
  47.     this.on(NodeEventType.CHILD_REMOVED, (child) => {
  48.         const removeAt = this._children.indexOf(child);
  49.         if (removeAt < 0) {
  50.             errorID(1633);
  51.             return;
  52.         }
  53.         this._children.splice(removeAt, 1);
  54.     });
  56.     ......
  57. };

Performance Comparison Results

opt-4.jpg

Parameter Array Object Pool

Up to version 3.6.0, Cocos Creator engine does not have an efficient memory pool implementation. When using the se (Script Engine Wrapper) for JS -> CPP interactions, temporary se::ValueArray args(argCount) objects need to be created. se::ValueArray is a ccstd::vector<se::Value> typedef, which leads to a significant amount of temporary memory allocations and deallocations, greatly impacting performance. This issue was not exposed in previous versions because the native code was relatively low-level and had fewer JSB calls. However, in version 3.6.0, with the increased native level hierarchy and JSB calls, this problem became more severe.

To address this issue, we came up with a solution: using an object pool to reuse se::ValueArray objects. The implementation of the object pool, se::ValueArrayPool, is relatively simple and is outlined below:

bindings/jswrapper/ValueArrayPool.h

  1. // CallbackDepthGuard class for resetting se::Value objects in a se::ValueArray after use
  2. // If the se::ValueArray is allocated with `new`, it will handle the `delete` process
  3. class CallbackDepthGuard final {
  4. public:
  5.     CallbackDepthGuard(ValueArray &arr, uint32_t &depth, bool needDelete)
  6.     : _arr(arr), _depth(depth), _needDelete(needDelete) {
  7.         ++_depth;
  8.     }
  10.     ~CallbackDepthGuard() {
  11.         --_depth;
  12.         for (auto &e : _arr) {
  13.             e.setUndefined();
  14.         }
  15.         if (_needDelete) {
  16.             delete &_arr;
  17.         }
  18.     }
  20. private:
  21.     ValueArray &_arr;
  22.     uint32_t &_depth;
  23.     const bool _needDelete{false};
  24. };
  26. class ValueArrayPool final {
  27. public:
  28.     // The maximum number of arguments for a bound function is 20
  29.     // If there are more than 20 arguments, consider refactoring the function parameters
  30.     static const uint32_t MAX_ARGS = 20;
  32.     ValueArrayPool();
  34.     ValueArray &get(uint32_t argc, bool &outNeedDelete);
  36.     uint32_t _depth{0};
  38. private:
  39.     void initPool(uint32_t index);
  40.     ccstd::vector<ccstd::array<ValueArray, MAX_ARGS + 1>> _pools;
  41. };
  43. extern ValueArrayPool gValueArrayPool;

bindings/jswrapper/ValueArrayPool.cpp

  1. ValueArrayPool gValueArrayPool;
  3. // Define the maximum depth as 5. If the depth exceeds this value, the object pool will not be used.
  4. #define SE_DEFAULT_MAX_DEPTH (5)
  6. ValueArrayPool::ValueArrayPool() {
  7.     _pools.resize(SE_DEFAULT_MAX_DEPTH);
  8.     for (uint32_t i = 0; i < SE_DEFAULT_MAX_DEPTH; ++i) {
  9.         initPool(i);
  10.     }
  11. }
  13. ValueArray &ValueArrayPool::get(uint32_t argc, bool &outNeedDelete) {
  14.     // If the depth is greater than the size of the object pool, directly create a new ValueArray object.
  15.     if (SE_UNLIKELY(_depth >= _pools.size())) {
  16.         outNeedDelete = true;
  17.         auto *ret = ccnew ValueArray();
  18.         ret->resize(argc);
  19.         return *ret;
  20.     }
  22.     outNeedDelete = false;
  23.     CC_ASSERT_LE(argc, MAX_ARGS);
  24.     // Retrieve a ValueArray object from the object pool.
  25.     auto &ret = _pools[_depth][argc];
  26.     CC_ASSERT(ret.size() == argc);
  27.     return ret;
  28. }
  30. // Initialize pool
  31. void ValueArrayPool::initPool(uint32_t index) {
  32.     auto &pool = _pools[index];
  33.     uint32_t i = 0;
  34.     for (auto &arr : pool) {
  35.         arr.resize(i);
  36.         ++i;
  37.     }
  38. }

Let’s look at the implementation of jsbFunctionWrapper function:

  1. SE_HOT void jsbFunctionWrapper(const v8::FunctionCallbackInfo<v8::Value> &v8args, se_function_ptr func, const char *funcName) {
  2.     bool ret = false;
  3.     v8::Isolate *isolate = v8args.GetIsolate();
  4.     v8::HandleScope scope(isolate);
  6.     /* Original code
  7.     se::ValueArray args;
  8.     args.reserve(10);
  9.     */
  11.     // Optimized implementation - Start
  12.     bool needDeleteValueArray{false};
  13.     // Retrieve a se::ValueArray from the global object pool, note that needDeleteValueArray is an output parameter
  14.     se::ValueArray &args = se::gValueArrayPool.get(v8args.Length(), needDeleteValueArray);
  15.     // Define a "callback depth guard" variable depthGuard, which automatically cleans up the object pool when it's destroyed
  16.     se::CallbackDepthGuard depthGuard{args, se::gValueArrayPool._depth, needDeleteValueArray};
  17.     // Optimized implementation - End
  19.     se::internal::jsToSeArgs(v8args, args);
  20.     se::Object *thisObject = se::internal::getPrivate(isolate, v8args.This());
  21.     se::State state(thisObject, args);
  22.     ret = func(state);
  23.     if (!ret) {
  24.         SE_LOGE("[ERROR] Failed to invoke %s\n", funcName);
  25.     }
  26.     se::internal::setReturnValue(state.rval(), v8args);
  27. }

Performance Comparison Results

opt-5.jpg

Conclusion

The main optimization techniques employed in Cocos Creator 3.6.0 native engine are as follows:

  1. Implementing the engine’s core modules in the native(C++) to leverage the performance of C++ code execution.
  2. Minimizing the frequency of cross-language interactions (JS <-> CPP) through the following five methods:
    • Shared memory: Improving performance by reducing memory copies.
    • Avoiding parameter passing: Using member variables instead of frequent parameter passing.
    • Caching properties: Storing frequently accessed properties in cache to avoid redundant retrieval.
    • Node synchronization: Synchronizing node changes through an event listening mechanism during node operations.
    • Parameter array object pool: Reusing parameter array objects using an object pool to reduce memory allocation and deallocation overhead.

By implementing these optimization measures, we have improved the performance of the Cocos Creator engine. These optimization techniques significantly reduce the overhead of cross-language interactions and enhance the overall performance and responsiveness of the engine.