iframe-proxy | Sunbelt Computer Software

643 lines (505 loc) · 17.8 KB
 * Tencent is pleased to support the open source community by making ScriptX available.
 * Copyright (C) 2021 THL A29 Limited, a Tencent company.  All rights reserved.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *      http://www.apache.org/licenses/LICENSE-2.0
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
#pragma once
#include <initializer_list>
#include <vector>
#include "Value.h"
#include "foundation.h"
#include "types.h"
#include SCRIPTX_BACKEND(Reference.h)
#include SCRIPTX_BACKEND(Engine.h)
#include SCRIPTX_BACKEND(Utils.h)
namespace script {
 * LocalReference inside a StackFrameScope.
 * use specialized Local Types like:
 * - Local<Value>
 * - Local<Object>
 * - Local<Function>
 * Move semantics:
 * 1. Local&lt;Value&gt; will be null after moved, and can still be used as a null reference.
 * 2. other local reference will be invalid after move, and should not be used anymore.
 * the default type intentionally left empty.
 * @tparam T
template <typename T>
class Local final {
  static_assert(std::is_base_of_v<Value, T>, "use specialized Local<T> with Value types");
  //    Local(const Local<T> &copy) noexcept;
  //    Local(Local<T> &&move) noexcept;
  //    Local<T> &operator=(const Local<T> &from);
  //    ~Local();
  //    Local<Value> toValue();
  //    operator Local<Value>() { return toValue(); }
  //    bool operator==(const Local<Value> &other) const;
  //    bool operator!=(const Local<Value> &other) const;
template <typename T>
void swap(Local<T>& lhs, Local<T> rhs) {
  lhs.swap(rhs);
 * A Global Reference, refers to a script value and prevent if from GCed.
 * Before destroy a ScriptEngine, all created Global ref should be destroyed or reset.
 * note: Only the default constructor can be called without EngineScope, (also can the destructor if
 * this reference is reset).
template <typename T>
class Global final {
  static_assert(std::is_base_of_v<Value, T>, "use Global<T> with Value types");
  // a null, can be called without EngineScope
  Global() noexcept;
  explicit Global(const Local<T>& localReference);
  explicit Global(const Weak<T>& weakReference);
  Global(const Global<T>& copy);
  Global(Global<T>&& move) noexcept;
  ~Global();
  Global<T>& operator=(const Global& assign);
  Global<T>& operator=(Global&& move) noexcept;
  void swap(Global& rhs) noexcept;
  Global<T>& operator=(const Local<T>& assign);
   * @return the value, throw if isEmpty() == true
  Local<T> get() const;
   * @return the value, null if isEmpty() == true
  Local<Value> getValue() const;
   * if this global is empty, being null is not empty!
  bool isEmpty() const;
  // clear to empty
  void reset();
  using InternalGlobalRef = typename internal::ImplType<Global>::type;
  InternalGlobalRef val_;
  friend class ScriptEngine;
  friend typename internal::ImplType<ScriptEngine>::type;
  template <typename R>
  friend class Local;
  template <typename R>
  friend class Weak;
template <typename T>
void swap(Global<T>& lhs, Global<T>& rhs) {
  lhs.swap(rhs);
 * Weak global reference.
 * A weak reference don't prevent object being garbage-collected.
 * note: on some platform GC is not predictable, some event don't have WeakRef implemented.
 * Use weak with caution.
 * @tparam T
template <typename T>
class Weak final {
  static_assert(std::is_base_of_v<Value, T>, "use Weak<T> with Value types");
  // a null, can be called without EngineScope
  Weak() noexcept;
  explicit Weak(const Local<T>& localReference);
  explicit Weak(const Global<T>& globalReference);
  Weak(const Weak<T>& copy);
  Weak(Weak<T>&& move) noexcept;
  Weak& operator=(const Weak<T>& assign);
  Weak& operator=(Weak<T>&& move) noexcept;
  void swap(Weak& rhs) noexcept;
  Weak& operator=(const Local<T>& assign);
   * @return the value, throw if getValue() returns null (either isEmpty() or GC collected the
   * value).
  Local<T> get() const;
   * @return the value, or null if isEmpty() == true or the value has been GCed
  Local<Value> getValue() const;
   * this weak is not set or has been reset
   * note: even if the weak reference is GCed, is still returns true
  bool isEmpty() const;
  void reset() noexcept;
  using InternalWeakRef = typename internal::ImplType<Weak>::type;
  InternalWeakRef val_;
  friend class ScriptEngine;
  friend typename internal::ImplType<ScriptEngine>::type;
  template <typename R>
  friend class Local;
  template <typename R>
  friend class Global;
template <typename T>
void swap(Weak<T>& lhs, Weak<T>& rhs) {
  lhs.swap(rhs);
// ==== Specialized Local Types ====
// forward declare of specialized string
template <>
class Local<String>;
#define SPECIALIZE_LOCAL(ValueType)                                               \
  Local(const Local<ValueType>& copy);                                            \
  Local(Local<ValueType>&& move) noexcept;                                        \
  Local<ValueType>& operator=(const Local& from);                                 \
  Local<ValueType>& operator=(Local&& move) noexcept;                             \
  void swap(Local& rhs) noexcept;                                                 \
  bool operator==(const Local<Value>& other) const;                               \
  bool operator!=(const Local<Value>& other) const { return !operator==(other); } \
  Local<String> describe() const;                                                 \
  std::string describeUtf8() const;                                               \
  SCRIPTX_DISALLOW_NEW();                                                         \
  using InternalLocalRef = typename internal::ImplType<Local<ValueType>>::type;   \
  InternalLocalRef val_;                                                          \
  explicit Local(InternalLocalRef internal);                                      \
  friend class ScriptEngine;                                                      \
  friend typename internal::ImplType<ScriptEngine>::type;                         \
  friend typename internal::ImplType<internal::interop>::type;                    \
  friend class ValueType;                                                         \
  friend InternalLocalRef;                                                        \
  template <typename R>                                                           \
  friend class Local;                                                             \
  template <typename R>                                                           \
  friend class Global;                                                            \
  template <typename R>                                                           \
  friend class Weak;                                                              \
  friend class Exception;
#define SPECIALIZE_NON_VALUE(ValueType)                                                        \
  Local<Value> asValue() const;                                                                \
  operator Local<Value>() const { return asValue(); }                                          \
  bool operator==(const Local<ValueType>& other) const { return operator==(other.asValue()); } \
  bool operator!=(const Local<ValueType>& other) const { return !operator==(other); }
template <>
class Local<Value> {
  SPECIALIZE_LOCAL(Value)
   * create a null reference
  Local() noexcept;
  ValueKind getKind() const;
  bool isNull() const;
  bool isObject() const;
  bool isString() const;
  bool isNumber() const;
  bool isBoolean() const;
  bool isFunction() const;
  bool isArray() const;
  bool isByteBuffer() const;
  bool isUnsupported() const;
  Local<Object> asObject() const;
  Local<Array> asArray() const;
  Local<ByteBuffer> asByteBuffer() const;
  Local<String> asString() const;
  Local<Number> asNumber() const;
  Local<Boolean> asBoolean() const;
  Local<Function> asFunction() const;
  Local<Unsupported> asUnsupported() const;
  Local<Value> asValue() const {
    // define this method to have consistent api with other Local types.
    return *this;
  void reset();
   * test whether two values are equal
   * impl-related.
   * in JS: same as js `===` operator
  // bool operator==(const Local<Value>& other);
template <>
class Local<Object> {
  SPECIALIZE_LOCAL(Object)
  Local<Value> get(const Local<String>& key) const;
  template <typename StringLike, StringLikeConcept(StringLike)>
  Local<Value> get(StringLike&& keyStringLike) const {
    return get(String::newString(std::forward<StringLike>(keyStringLike)));
  void set(const Local<String>& key, const Local<Value>& value) const;
   * @param value any thing supported by the type converter
  template <typename T>
  void set(const Local<String>& key, T&& value) const;
   * @param keyStringLike any thing can fit in String::new(keyStringLike) or Local<String>
   * @param value any thing supported by the type converter
  template <typename StringLike, typename T = Local<Value>, StringLikeConcept(StringLike)>
  void set(StringLike&& keyStringLike, T&& value) const;
  void remove(const Local<String>& key) const;
  template <typename StringLike, StringLikeConcept(StringLike)>
  void remove(StringLike&& keyStringLike) const {
    remove(String::newString(std::forward<StringLike>(keyStringLike)));
  bool has(const Local<String>& key) const;
  template <typename StringLike, StringLikeConcept(StringLike)>
  bool has(StringLike&& keyStringLike) const {
    return has(String::newString(std::forward<StringLike>(keyStringLike)));
   * @return this instanceof type
  bool instanceOf(const Local<Value>& type) const;
   * @return all keys to enumerate properties of this object
  std::vector<Local<String>> getKeys() const;
   * @return all keys to enumerate properties of this object
  std::vector<std::string> getKeyNames() const;
  SPECIALIZE_NON_VALUE(Object)
template <>
class Local<String> {
  SPECIALIZE_LOCAL(String)
   * avoid memory copy, provides better performance.
   * especially useful when requires string_view or c string
   * auto holder = s.toStringHolder();
   * printf("%s", holder.c_str());
   * \endcode
   * \see StringHolder
  StringHolder toStringHolder() const;
  std::string toString() const;
#ifdef __cpp_char8_t
  std::u8string toU8string() const;
  SPECIALIZE_NON_VALUE(String)
  friend class StringHolder;
template <>
class Local<Number> {
  SPECIALIZE_LOCAL(Number)
  int32_t toInt32() const;
  int64_t toInt64() const;
  float toFloat() const;
  double toDouble() const;
  SPECIALIZE_NON_VALUE(Number)
template <>
class Local<Boolean> {
  SPECIALIZE_LOCAL(Boolean)
  bool value() const;
  SPECIALIZE_NON_VALUE(Boolean)
template <>
class Local<Function> {
  SPECIALIZE_LOCAL(Function)
   * @param thiz the receiver of the function
   * @param args function arguments
   * @return function return value
  Local<Value> call(const Local<Value>& thiz, const std::vector<Local<Value>>& args) const {
    return callImpl(thiz, args.size(), args.data());
   * @param thiz the receiver of the function, default to null
   * @param args function arguments
   * @return function return value
  Local<Value> call(const Local<Value>& thiz,
                    const std::initializer_list<Local<Value>>& args) const {
    return callImpl(thiz, args.size(), args.begin());
   * typesafe variadic template helper method
   * @tparam T MUST BE local reference, ie: Local<Type>. or supported raw C++ type to convert.
   * @param thiz the receiver of the function, default to null
   * @param args function arguments
   * @return function return value
  template <typename... T>
  Local<Value> call(const Local<Value>& thiz, T&&... args) const;
   * helper function to call with null thiz(receiver) and no arguments.
  Local<Value> call() const { return call({}); }
   * create a C++ function wrapping a Local<Function>
   * // example:
   * Local<Function> add = ...
   * auto func = add.wrapper<int(int,int)>();
   * func(1, 2) == 3;
   * \endcode
   * @tparam FuncType function signature, like "int(int, int)" or "std::string(const char*, int)"
   * @return a std::function
   * @param thiz the receiver of the function, default to null
   * @note the returned std::function holds a Global<Function> to the function and receiver
   * reference, and will be auto released when destroy engine, after that, the returned
   * std::function is not valid anymore.
  // implemented in Native.hpp
  template <typename FuncType>
  std::function<FuncType> wrapper(const Local<Value>& thiz = {}) const;
  SPECIALIZE_NON_VALUE(Function)
  Local<Value> callImpl(const Local<Value>& thiz, size_t size, const Local<Value>* args) const;
template <>
class Local<Array> {
  SPECIALIZE_LOCAL(Array)
  size_t size() const;
  Local<Value> get(size_t index) const;
  void set(size_t index, const Local<Value>& value) const;
   * @param value any thing supported by the type converter
  template <typename T>
  void set(size_t index, T&& value) const;
  void add(const Local<Value>& value) const;
  void clear() const;
  SPECIALIZE_NON_VALUE(Array)
 * ByteBuffer represents a chunk of memory that you can exchange data between ScriptEngine and C++.
 * For JavaScript language these are ArrayBuffer, or any TypedArray.
 * There are two kinds of ByteBuffer.
 * 1. shared.
 * 2. non-shared.
 * For instance, when we have a "data = new ArrayBuffer()" in js,
 * and passed to C++ as "Local<ByteBuffer> bytes".
 * Shared means "data" and "bytes" can point to the same memory address, so any write on "data" can
 * be seen on "bytes", and vice-versa.
 * Non-shared means we can't get the pointer of "data" to the memory chunk(usually the current
 * backend not support this), so we have to make a copy of it. In this case, we need two more
 * operations: "sync" to copy data form "data" to "bytes" and "commit" to copy from "bytes" to
 * For now, V8 and JavaScriptCore backend support full shared, that is all ByteBuffer are shared.
 * For Wasm back end it's different, please read the doc.
 * But you can always use a shared byte buffer as no non-shared, "commit" & "sync" on it would be
template <>
class Local<ByteBuffer> {
  SPECIALIZE_LOCAL(ByteBuffer)
   * get the underlying raw bytes
   * @return the raw pointer, caller does NOT OWN this pointer!
   * And it's only valid during the Local<ByteArray> lifecycle.
   * This is a cheaper call (depends on implementation)
   * compared to getRawBytesShared(), use this one when you
   * just want to get the raw bytes temporarily.
  void* getRawBytes() const;
   * get the underlying raw bytes
   * @return the raw pointer, caller OWN the shared_ptr,
   * and the shared_ptr stay valid until the engine is destroyed.
   * 1. caller should release the shared_ptr before destroying ScriptEngine.
   * 2. getRawBytes() == getRawBytesShared().get()
   * 3. getRawBytesShared() maybe more expensive compared to getRawBytes() depends on
   * implementations.
  std::shared_ptr<void> getRawBytesShared() const;
   * @return size of raw bytes, in unit of byte
  size_t byteLength() const;
   * @return count of elements (uint8, uint32, etc).
   * use getType() to fetch element type.
  size_t elementCount() const { return byteLength() / ByteBuffer::getTypeSize(getType()); }
   * @return the content type
  ByteBuffer::Type getType() const;
   * If the ByteBuffer is a shared ByteBuffer.
   * Read class doc for more detail about shared & non-shared.
  bool isShared() const;
   * If the ByteBuffer is non-shared, copy data from C++ to Script.
   * For shared ByteBuffer, this is a noop.
  void commit() const;
   * If the ByteBuffer is non-shared, copy data from Script to C++.
   * For shared ByteBuffer, this is a noop.
  void sync() const;
  SPECIALIZE_NON_VALUE(ByteBuffer);
template <>
class Local<Unsupported> {
  SPECIALIZE_LOCAL(Unsupported)
  SPECIALIZE_NON_VALUE(Unsupported)
#undef SPECIALIZE_LOCAL
#undef SPECIALIZE_NON_VALUE
}  // namespace script
Sunbelt Computer Software

PL/B Language Development and Support

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Sunbelt Computer Software

PL/B Language Development and Support

Uh oh!

FilesExpand file tree

Reference.h

Latest commit

History

Reference.h

File metadata and controls
