source/scriptinterface/StructuredClone.h

   1 /* Copyright (C) 2021 Wildfire Games.
   2  * This file is part of 0 A.D.
   3  *
   4  * 0 A.D. is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation, either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * 0 A.D. is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with 0 A.D.  If not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 #ifndef INCLUDED_SCRIPTINTERFACE_STRUCTUREDCLONE
  19 #define INCLUDED_SCRIPTINTERFACE_STRUCTUREDCLONE
  20
  21 #include "ScriptForward.h"
  22
  23 #include <memory>
  24
  25 class JSStructuredCloneData;
  26
  27 namespace Script
  28 {
  29 /**
  30  * Structured clones are a way to serialize 'simple' JS::Values into a buffer
  31  * that can safely be passed between compartments and between threads.
  32  * A StructuredClone can be stored and read multiple times if desired.
  33  * We wrap them in shared_ptr so memory management is automatic and
  34  * thread-safe.
  35  */
  36 using StructuredClone = std::shared_ptr<JSStructuredCloneData>;
  37
  38 StructuredClone WriteStructuredClone(const ScriptRequest& rq, JS::HandleValue v);
  39 void ReadStructuredClone(const ScriptRequest& rq, const StructuredClone& ptr, JS::MutableHandleValue ret);
  40
  41 /**
  42  * Construct a new value by cloning a value (possibly from a different Compartment).
  43  * Complex values (functions, XML, etc) won't be cloned correctly, but basic
  44  * types and cyclic references should be fine.
  45  * Takes ScriptInterfaces to enter the correct realm.
  46  * Caller beware - manipulating several compartments in the same function is tricky.
  47  * @param to - ScriptInterface of the target. Should match the rooting context of the result.
  48  * @param from - ScriptInterface of @a val.
  49  */
  50 JS::Value CloneValueFromOtherCompartment(const ScriptInterface& to, const ScriptInterface& from, JS::HandleValue val);
  51
  52 /**
  53  * Clone a JS value, ensuring that changes to the result
  54  * won't affect the original value.
  55  * Works by cloning, so the same restrictions as CloneValueFromOtherCompartment apply.
  56  */
  57 JS::Value DeepCopy(const ScriptRequest& rq, JS::HandleValue val);
  58
  59 } // namespace Script
  60
  61 #endif // INCLUDED_SCRIPTINTERFACE_STRUCTUREDCLONE