Line data    Source code

       1             : /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
       2             : /* This Source Code Form is subject to the terms of the Mozilla Public
       3             :  * License, v. 2.0. If a copy of the MPL was not distributed with this
       4             :  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
       5             : 
       6             : /* SpiderMonkey initialization and shutdown APIs. */
       7             : 
       8             : #ifndef js_Initialization_h
       9             : #define js_Initialization_h
      10             : 
      11             : #include "jstypes.h"
      12             : 
      13             : namespace JS {
      14             : namespace detail {
      15             : 
      16             : enum class InitState { Uninitialized = 0, Running, ShutDown };
      17             : 
      18             : /**
      19             :  * SpiderMonkey's initialization status is tracked here, and it controls things
      20             :  * that should happen only once across all runtimes.  It's an API requirement
      21             :  * that JS_Init (and JS_ShutDown, if called) be called in a thread-aware
      22             :  * manner, so this (internal -- embedders, don't use!) variable doesn't need to
      23             :  * be atomic.
      24             :  */
      25             : extern JS_PUBLIC_DATA(InitState)
      26             : libraryInitState;
      27             : 
      28             : extern JS_PUBLIC_API(const char*)
      29             : InitWithFailureDiagnostic(bool isDebugBuild);
      30             : 
      31             : } // namespace detail
      32             : } // namespace JS
      33             : 
      34             : // These are equivalent to ICU's |UMemAllocFn|, |UMemReallocFn|, and
      35             : // |UMemFreeFn| types.  The first argument (called |context| in the ICU docs)
      36             : // will always be nullptr and should be ignored.
      37             : typedef void* (*JS_ICUAllocFn)(const void*, size_t size);
      38             : typedef void* (*JS_ICUReallocFn)(const void*, void* p, size_t size);
      39             : typedef void (*JS_ICUFreeFn)(const void*, void* p);
      40             : 
      41             : /**
      42             :  * This function can be used to track memory used by ICU.  If it is called, it
      43             :  * *must* be called before JS_Init.  Don't use it unless you know what you're
      44             :  * doing!
      45             :  */
      46             : extern JS_PUBLIC_API(bool)
      47             : JS_SetICUMemoryFunctions(JS_ICUAllocFn allocFn,
      48             :                          JS_ICUReallocFn reallocFn,
      49             :                          JS_ICUFreeFn freeFn);
      50             : 
      51             : /**
      52             :  * Initialize SpiderMonkey, returning true only if initialization succeeded.
      53             :  * Once this method has succeeded, it is safe to call JS_NewRuntime and other
      54             :  * JSAPI methods.
      55             :  *
      56             :  * This method must be called before any other JSAPI method is used on any
      57             :  * thread.  Once it has been used, it is safe to call any JSAPI method, and it
      58             :  * remains safe to do so until JS_ShutDown is correctly called.
      59             :  *
      60             :  * It is currently not possible to initialize SpiderMonkey multiple times (that
      61             :  * is, calling JS_Init/JSAPI methods/JS_ShutDown in that order, then doing so
      62             :  * again).  This restriction may eventually be lifted.
      63             :  */
      64             : inline bool
      65             : JS_Init(void)
      66             : {
      67             : #ifdef DEBUG
      68             :     return !JS::detail::InitWithFailureDiagnostic(true);
      69             : #else
      70             :     return !JS::detail::InitWithFailureDiagnostic(false);
      71             : #endif
      72             : }
      73             : 
      74             : /**
      75             :  * A variant of JS_Init. On success it returns nullptr. On failure it returns a
      76             :  * pointer to a string literal that describes how initialization failed, which
      77             :  * can be useful for debugging purposes.
      78             :  */
      79             : inline const char*
      80           3 : JS_InitWithFailureDiagnostic(void)
      81             : {
      82             : #ifdef DEBUG
      83           3 :     return JS::detail::InitWithFailureDiagnostic(true);
      84             : #else
      85             :     return JS::detail::InitWithFailureDiagnostic(false);
      86             : #endif
      87             : }
      88             : 
      89             : /*
      90             :  * Returns true if SpiderMonkey has been initialized successfully, even if it has
      91             :  * possibly been shut down.
      92             :  *
      93             :  * Note that it is the responsibility of the embedder to call JS_Init() and
      94             :  * JS_ShutDown() at the correct times, and therefore this API should ideally not
      95             :  * be necessary to use.  This is only intended to be used in cases where the
      96             :  * embedder isn't in full control of deciding whether to initialize SpiderMonkey
      97             :  * or hand off the task to another consumer.
      98             :  */
      99             : inline bool
     100             : JS_IsInitialized(void)
     101             : {
     102             :   return JS::detail::libraryInitState != JS::detail::InitState::Uninitialized;
     103             : }
     104             : 
     105             : /**
     106             :  * Destroy free-standing resources allocated by SpiderMonkey, not associated
     107             :  * with any runtime, context, or other structure.
     108             :  *
     109             :  * This method should be called after all other JSAPI data has been properly
     110             :  * cleaned up: every new runtime must have been destroyed, every new context
     111             :  * must have been destroyed, and so on.  Calling this method before all other
     112             :  * resources have been destroyed has undefined behavior.
     113             :  *
     114             :  * Failure to call this method, at present, has no adverse effects other than
     115             :  * leaking memory.  This may not always be the case; it's recommended that all
     116             :  * embedders call this method when all other JSAPI operations have completed.
     117             :  *
     118             :  * It is currently not possible to initialize SpiderMonkey multiple times (that
     119             :  * is, calling JS_Init/JSAPI methods/JS_ShutDown in that order, then doing so
     120             :  * again).  This restriction may eventually be lifted.
     121             :  */
     122             : extern JS_PUBLIC_API(void)
     123             : JS_ShutDown(void);
     124             : 
     125             : #endif /* js_Initialization_h */