/work/obj-fuzz/dist/include/js/Initialization.h

Source (jump to first uncovered line)
/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

/* SpiderMonkey initialization and shutdown APIs. */

#ifndef js_Initialization_h
#define js_Initialization_h

#include "jstypes.h"

namespace JS {
namespace detail {

enum class InitState {
    Uninitialized = 0,
    Initializing,
    Running,
    ShutDown
};

/**
 * SpiderMonkey's initialization status is tracked here, and it controls things
 * that should happen only once across all runtimes.  It's an API requirement
 * that JS_Init (and JS_ShutDown, if called) be called in a thread-aware
 * manner, so this (internal -- embedders, don't use!) variable doesn't need to
 * be atomic.
 */
extern JS_PUBLIC_DATA(InitState)
libraryInitState;

extern JS_PUBLIC_API(const char*)
InitWithFailureDiagnostic(bool isDebugBuild);

} // namespace detail
} // namespace JS

// These are equivalent to ICU's |UMemAllocFn|, |UMemReallocFn|, and
// |UMemFreeFn| types.  The first argument (called |context| in the ICU docs)
// will always be nullptr and should be ignored.
typedef void* (*JS_ICUAllocFn)(const void*, size_t size);
typedef void* (*JS_ICUReallocFn)(const void*, void* p, size_t size);
typedef void (*JS_ICUFreeFn)(const void*, void* p);

/**
 * This function can be used to track memory used by ICU.  If it is called, it
 * *must* be called before JS_Init.  Don't use it unless you know what you're
 * doing!
 */
extern JS_PUBLIC_API(bool)
JS_SetICUMemoryFunctions(JS_ICUAllocFn allocFn,
                         JS_ICUReallocFn reallocFn,
                         JS_ICUFreeFn freeFn);

#ifdef ENABLE_BIGINT
namespace JS {

// These types are documented as allocate_function, reallocate_function,
// and free_function in the Info node `(gmp)Custom Allocation`.
using GMPAllocFn = void* (*)(size_t allocSize);
using GMPReallocFn = void* (*)(void* p, size_t oldSize, size_t newSize);
using GMPFreeFn = void (*)(void* p, size_t size);

// This function can be used to track memory used by GMP. If it is
// called, it *must* be called before JS_Init so that same functions are
// used for all allocations.
extern JS_PUBLIC_API(void)
SetGMPMemoryFunctions(GMPAllocFn allocFn,
                      GMPReallocFn reallocFn,
                      GMPFreeFn freeFn);

}; // namespace JS
#endif

/**
 * Initialize SpiderMonkey, returning true only if initialization succeeded.
 * Once this method has succeeded, it is safe to call JS_NewContext and other
 * JSAPI methods.
 *
 * This method must be called before any other JSAPI method is used on any
 * thread.  Once it has been used, it is safe to call any JSAPI method, and it
 * remains safe to do so until JS_ShutDown is correctly called.
 *
 * It is currently not possible to initialize SpiderMonkey multiple times (that
 * is, calling JS_Init/JSAPI methods/JS_ShutDown in that order, then doing so
 * again).  This restriction may eventually be lifted.
 */
inline bool
JS_Init(void)
{
#ifdef DEBUG
    return !JS::detail::InitWithFailureDiagnostic(true);
#else
    return !JS::detail::InitWithFailureDiagnostic(false);
#endif
}

/**
 * A variant of JS_Init. On success it returns nullptr. On failure it returns a
 * pointer to a string literal that describes how initialization failed, which
 * can be useful for debugging purposes.
 */
inline const char*
JS_InitWithFailureDiagnostic(void)
{
#ifdef DEBUG
    return JS::detail::InitWithFailureDiagnostic(true);
#else
    return JS::detail::InitWithFailureDiagnostic(false);
#endif
}

/*
 * Returns true if SpiderMonkey has been initialized successfully, even if it has
 * possibly been shut down.
 *
 * Note that it is the responsibility of the embedder to call JS_Init() and
 * JS_ShutDown() at the correct times, and therefore this API should ideally not
 * be necessary to use.  This is only intended to be used in cases where the
 * embedder isn't in full control of deciding whether to initialize SpiderMonkey
 * or hand off the task to another consumer.
 */
inline bool
JS_IsInitialized(void)
{
  return JS::detail::libraryInitState >= JS::detail::InitState::Running;
}

/**
 * Destroy free-standing resources allocated by SpiderMonkey, not associated
 * with any runtime, context, or other structure.
 *
 * This method should be called after all other JSAPI data has been properly
 * cleaned up: every new runtime must have been destroyed, every new context
 * must have been destroyed, and so on.  Calling this method before all other
 * resources have been destroyed has undefined behavior.
 *
 * Failure to call this method, at present, has no adverse effects other than
 * leaking memory.  This may not always be the case; it's recommended that all
 * embedders call this method when all other JSAPI operations have completed.
 *
 * It is currently not possible to initialize SpiderMonkey multiple times (that
 * is, calling JS_Init/JSAPI methods/JS_ShutDown in that order, then doing so
 * again).  This restriction may eventually be lifted.
 */
extern JS_PUBLIC_API(void)
JS_ShutDown(void);

#endif /* js_Initialization_h */

Line	Count	Source (jump to first uncovered line)
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 {
17		Uninitialized = 0,
18		Initializing,
19		Running,
20		ShutDown
21		};
22
23		/**
24		* SpiderMonkey's initialization status is tracked here, and it controls things
25		* that should happen only once across all runtimes. It's an API requirement
26		* that JS_Init (and JS_ShutDown, if called) be called in a thread-aware
27		* manner, so this (internal -- embedders, don't use!) variable doesn't need to
28		* be atomic.
29		*/
30		extern JS_PUBLIC_DATA(InitState)
31		libraryInitState;
32
33		extern JS_PUBLIC_API(const char*)
34		InitWithFailureDiagnostic(bool isDebugBuild);
35
36		} // namespace detail
37		} // namespace JS
38
39		// These are equivalent to ICU's \|UMemAllocFn\|, \|UMemReallocFn\|, and
40		// \|UMemFreeFn\| types. The first argument (called \|context\| in the ICU docs)
41		// will always be nullptr and should be ignored.
42		typedef void* (JS_ICUAllocFn)(const void, size_t size);
43		typedef void* (JS_ICUReallocFn)(const void, void* p, size_t size);
44		typedef void (JS_ICUFreeFn)(const void, void* p);
45
46		/**
47		* This function can be used to track memory used by ICU. If it is called, it
48		* must be called before JS_Init. Don't use it unless you know what you're
49		* doing!
50		*/
51		extern JS_PUBLIC_API(bool)
52		JS_SetICUMemoryFunctions(JS_ICUAllocFn allocFn,
53		JS_ICUReallocFn reallocFn,
54		JS_ICUFreeFn freeFn);
55
56		#ifdef ENABLE_BIGINT
57		namespace JS {
58
59		// These types are documented as allocate_function, reallocate_function,
60		// and free_function in the Info node `(gmp)Custom Allocation`.
61		using GMPAllocFn = void* (*)(size_t allocSize);
62		using GMPReallocFn = void* ()(void p, size_t oldSize, size_t newSize);
63		using GMPFreeFn = void ()(void p, size_t size);
64
65		// This function can be used to track memory used by GMP. If it is
66		// called, it must be called before JS_Init so that same functions are
67		// used for all allocations.
68		extern JS_PUBLIC_API(void)
69		SetGMPMemoryFunctions(GMPAllocFn allocFn,
70		GMPReallocFn reallocFn,
71		GMPFreeFn freeFn);
72
73		}; // namespace JS
74		#endif
75
76		/**
77		* Initialize SpiderMonkey, returning true only if initialization succeeded.
78		* Once this method has succeeded, it is safe to call JS_NewContext and other
79		* JSAPI methods.
80		*
81		* This method must be called before any other JSAPI method is used on any
82		* thread. Once it has been used, it is safe to call any JSAPI method, and it
83		* remains safe to do so until JS_ShutDown is correctly called.
84		*
85		* It is currently not possible to initialize SpiderMonkey multiple times (that
86		* is, calling JS_Init/JSAPI methods/JS_ShutDown in that order, then doing so
87		* again). This restriction may eventually be lifted.
88		*/
89		inline bool
90		JS_Init(void)
91	0	{
92	0	#ifdef DEBUG
93	0	return !JS::detail::InitWithFailureDiagnostic(true);
94	0	#else
95	0	return !JS::detail::InitWithFailureDiagnostic(false);
96	0	#endif
97	0	}
98
99		/**
100		* A variant of JS_Init. On success it returns nullptr. On failure it returns a
101		* pointer to a string literal that describes how initialization failed, which
102		* can be useful for debugging purposes.
103		*/
104		inline const char*
105		JS_InitWithFailureDiagnostic(void)
106	3	{
107		#ifdef DEBUG
108		return JS::detail::InitWithFailureDiagnostic(true);
109		#else
110		return JS::detail::InitWithFailureDiagnostic(false);
111	3	#endif
112	3	}
113
114		/*
115		* Returns true if SpiderMonkey has been initialized successfully, even if it has
116		* possibly been shut down.
117		*
118		* Note that it is the responsibility of the embedder to call JS_Init() and
119		* JS_ShutDown() at the correct times, and therefore this API should ideally not
120		* be necessary to use. This is only intended to be used in cases where the
121		* embedder isn't in full control of deciding whether to initialize SpiderMonkey
122		* or hand off the task to another consumer.
123		*/
124		inline bool
125		JS_IsInitialized(void)
126	0	{
127	0	return JS::detail::libraryInitState >= JS::detail::InitState::Running;
128	0	}
129
130		/**
131		* Destroy free-standing resources allocated by SpiderMonkey, not associated
132		* with any runtime, context, or other structure.
133		*
134		* This method should be called after all other JSAPI data has been properly
135		* cleaned up: every new runtime must have been destroyed, every new context
136		* must have been destroyed, and so on. Calling this method before all other
137		* resources have been destroyed has undefined behavior.
138		*
139		* Failure to call this method, at present, has no adverse effects other than
140		* leaking memory. This may not always be the case; it's recommended that all
141		* embedders call this method when all other JSAPI operations have completed.
142		*
143		* It is currently not possible to initialize SpiderMonkey multiple times (that
144		* is, calling JS_Init/JSAPI methods/JS_ShutDown in that order, then doing so
145		* again). This restriction may eventually be lifted.
146		*/
147		extern JS_PUBLIC_API(void)
148		JS_ShutDown(void);
149
150		#endif /* js_Initialization_h */

Coverage Report

Created: 2018-09-25 14:53