OLD | NEW |
| (Empty) |
1 // Copyright 2011 the V8 project authors. All rights reserved. | |
2 // Redistribution and use in source and binary forms, with or without | |
3 // modification, are permitted provided that the following conditions are | |
4 // met: | |
5 // | |
6 // * Redistributions of source code must retain the above copyright | |
7 // notice, this list of conditions and the following disclaimer. | |
8 // * Redistributions in binary form must reproduce the above | |
9 // copyright notice, this list of conditions and the following | |
10 // disclaimer in the documentation and/or other materials provided | |
11 // with the distribution. | |
12 // * Neither the name of Google Inc. nor the names of its | |
13 // contributors may be used to endorse or promote products derived | |
14 // from this software without specific prior written permission. | |
15 // | |
16 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
17 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
18 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | |
19 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | |
20 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
21 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
22 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | |
23 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | |
24 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
25 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | |
26 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
27 | |
28 /** \mainpage V8 API Reference Guide | |
29 * | |
30 * V8 is Google's open source JavaScript engine. | |
31 * | |
32 * This set of documents provides reference material generated from the | |
33 * V8 header file, include/v8.h. | |
34 * | |
35 * For other documentation see http://code.google.com/apis/v8/ | |
36 */ | |
37 | |
38 #ifndef V8_H_ | |
39 #define V8_H_ | |
40 | |
41 #include "v8stdint.h" | |
42 | |
43 #ifdef _WIN32 | |
44 | |
45 // Setup for Windows DLL export/import. When building the V8 DLL the | |
46 // BUILDING_V8_SHARED needs to be defined. When building a program which uses | |
47 // the V8 DLL USING_V8_SHARED needs to be defined. When either building the V8 | |
48 // static library or building a program which uses the V8 static library neither | |
49 // BUILDING_V8_SHARED nor USING_V8_SHARED should be defined. | |
50 #if defined(BUILDING_V8_SHARED) && defined(USING_V8_SHARED) | |
51 #error both BUILDING_V8_SHARED and USING_V8_SHARED are set - please check the\ | |
52 build configuration to ensure that at most one of these is set | |
53 #endif | |
54 | |
55 #ifdef BUILDING_V8_SHARED | |
56 #define V8EXPORT __declspec(dllexport) | |
57 #elif USING_V8_SHARED | |
58 #define V8EXPORT __declspec(dllimport) | |
59 #else | |
60 #define V8EXPORT | |
61 #endif // BUILDING_V8_SHARED | |
62 | |
63 #else // _WIN32 | |
64 | |
65 // Setup for Linux shared library export. There is no need to distinguish | |
66 // between building or using the V8 shared library, but we should not | |
67 // export symbols when we are building a static library. | |
68 #if defined(__GNUC__) && (__GNUC__ >= 4) && defined(V8_SHARED) | |
69 #define V8EXPORT __attribute__ ((visibility("default"))) | |
70 #else // defined(__GNUC__) && (__GNUC__ >= 4) | |
71 #define V8EXPORT | |
72 #endif // defined(__GNUC__) && (__GNUC__ >= 4) | |
73 | |
74 #endif // _WIN32 | |
75 | |
76 /** | |
77 * The v8 JavaScript engine. | |
78 */ | |
79 namespace v8 { | |
80 | |
81 class Context; | |
82 class String; | |
83 class StringObject; | |
84 class Value; | |
85 class Utils; | |
86 class Number; | |
87 class NumberObject; | |
88 class Object; | |
89 class Array; | |
90 class Int32; | |
91 class Uint32; | |
92 class External; | |
93 class Primitive; | |
94 class Boolean; | |
95 class BooleanObject; | |
96 class Integer; | |
97 class Function; | |
98 class Date; | |
99 class ImplementationUtilities; | |
100 class Signature; | |
101 template <class T> class Handle; | |
102 template <class T> class Local; | |
103 template <class T> class Persistent; | |
104 class FunctionTemplate; | |
105 class ObjectTemplate; | |
106 class Data; | |
107 class AccessorInfo; | |
108 class StackTrace; | |
109 class StackFrame; | |
110 | |
111 namespace internal { | |
112 | |
113 class Arguments; | |
114 class Object; | |
115 class Heap; | |
116 class HeapObject; | |
117 class Isolate; | |
118 } | |
119 | |
120 | |
121 // --- Weak Handles --- | |
122 | |
123 | |
124 /** | |
125 * A weak reference callback function. | |
126 * | |
127 * This callback should either explicitly invoke Dispose on |object| if | |
128 * V8 wrapper is not needed anymore, or 'revive' it by invocation of MakeWeak. | |
129 * | |
130 * \param object the weak global object to be reclaimed by the garbage collector | |
131 * \param parameter the value passed in when making the weak global object | |
132 */ | |
133 typedef void (*WeakReferenceCallback)(Persistent<Value> object, | |
134 void* parameter); | |
135 | |
136 | |
137 // --- Handles --- | |
138 | |
139 #define TYPE_CHECK(T, S) \ | |
140 while (false) { \ | |
141 *(static_cast<T* volatile*>(0)) = static_cast<S*>(0); \ | |
142 } | |
143 | |
144 /** | |
145 * An object reference managed by the v8 garbage collector. | |
146 * | |
147 * All objects returned from v8 have to be tracked by the garbage | |
148 * collector so that it knows that the objects are still alive. Also, | |
149 * because the garbage collector may move objects, it is unsafe to | |
150 * point directly to an object. Instead, all objects are stored in | |
151 * handles which are known by the garbage collector and updated | |
152 * whenever an object moves. Handles should always be passed by value | |
153 * (except in cases like out-parameters) and they should never be | |
154 * allocated on the heap. | |
155 * | |
156 * There are two types of handles: local and persistent handles. | |
157 * Local handles are light-weight and transient and typically used in | |
158 * local operations. They are managed by HandleScopes. Persistent | |
159 * handles can be used when storing objects across several independent | |
160 * operations and have to be explicitly deallocated when they're no | |
161 * longer used. | |
162 * | |
163 * It is safe to extract the object stored in the handle by | |
164 * dereferencing the handle (for instance, to extract the Object* from | |
165 * a Handle<Object>); the value will still be governed by a handle | |
166 * behind the scenes and the same rules apply to these values as to | |
167 * their handles. | |
168 */ | |
169 template <class T> class Handle { | |
170 public: | |
171 /** | |
172 * Creates an empty handle. | |
173 */ | |
174 inline Handle() : val_(0) {} | |
175 | |
176 /** | |
177 * Creates a new handle for the specified value. | |
178 */ | |
179 inline explicit Handle(T* val) : val_(val) {} | |
180 | |
181 /** | |
182 * Creates a handle for the contents of the specified handle. This | |
183 * constructor allows you to pass handles as arguments by value and | |
184 * to assign between handles. However, if you try to assign between | |
185 * incompatible handles, for instance from a Handle<String> to a | |
186 * Handle<Number> it will cause a compile-time error. Assigning | |
187 * between compatible handles, for instance assigning a | |
188 * Handle<String> to a variable declared as Handle<Value>, is legal | |
189 * because String is a subclass of Value. | |
190 */ | |
191 template <class S> inline Handle(Handle<S> that) | |
192 : val_(reinterpret_cast<T*>(*that)) { | |
193 /** | |
194 * This check fails when trying to convert between incompatible | |
195 * handles. For example, converting from a Handle<String> to a | |
196 * Handle<Number>. | |
197 */ | |
198 TYPE_CHECK(T, S); | |
199 } | |
200 | |
201 /** | |
202 * Returns true if the handle is empty. | |
203 */ | |
204 inline bool IsEmpty() const { return val_ == 0; } | |
205 | |
206 /** | |
207 * Sets the handle to be empty. IsEmpty() will then return true. | |
208 */ | |
209 inline void Clear() { val_ = 0; } | |
210 | |
211 inline T* operator->() const { return val_; } | |
212 | |
213 inline T* operator*() const { return val_; } | |
214 | |
215 /** | |
216 * Checks whether two handles are the same. | |
217 * Returns true if both are empty, or if the objects | |
218 * to which they refer are identical. | |
219 * The handles' references are not checked. | |
220 */ | |
221 template <class S> inline bool operator==(Handle<S> that) const { | |
222 internal::Object** a = reinterpret_cast<internal::Object**>(**this); | |
223 internal::Object** b = reinterpret_cast<internal::Object**>(*that); | |
224 if (a == 0) return b == 0; | |
225 if (b == 0) return false; | |
226 return *a == *b; | |
227 } | |
228 | |
229 /** | |
230 * Checks whether two handles are different. | |
231 * Returns true if only one of the handles is empty, or if | |
232 * the objects to which they refer are different. | |
233 * The handles' references are not checked. | |
234 */ | |
235 template <class S> inline bool operator!=(Handle<S> that) const { | |
236 return !operator==(that); | |
237 } | |
238 | |
239 template <class S> static inline Handle<T> Cast(Handle<S> that) { | |
240 #ifdef V8_ENABLE_CHECKS | |
241 // If we're going to perform the type check then we have to check | |
242 // that the handle isn't empty before doing the checked cast. | |
243 if (that.IsEmpty()) return Handle<T>(); | |
244 #endif | |
245 return Handle<T>(T::Cast(*that)); | |
246 } | |
247 | |
248 template <class S> inline Handle<S> As() { | |
249 return Handle<S>::Cast(*this); | |
250 } | |
251 | |
252 private: | |
253 T* val_; | |
254 }; | |
255 | |
256 | |
257 /** | |
258 * A light-weight stack-allocated object handle. All operations | |
259 * that return objects from within v8 return them in local handles. They | |
260 * are created within HandleScopes, and all local handles allocated within a | |
261 * handle scope are destroyed when the handle scope is destroyed. Hence it | |
262 * is not necessary to explicitly deallocate local handles. | |
263 */ | |
264 template <class T> class Local : public Handle<T> { | |
265 public: | |
266 inline Local(); | |
267 template <class S> inline Local(Local<S> that) | |
268 : Handle<T>(reinterpret_cast<T*>(*that)) { | |
269 /** | |
270 * This check fails when trying to convert between incompatible | |
271 * handles. For example, converting from a Handle<String> to a | |
272 * Handle<Number>. | |
273 */ | |
274 TYPE_CHECK(T, S); | |
275 } | |
276 template <class S> inline Local(S* that) : Handle<T>(that) { } | |
277 template <class S> static inline Local<T> Cast(Local<S> that) { | |
278 #ifdef V8_ENABLE_CHECKS | |
279 // If we're going to perform the type check then we have to check | |
280 // that the handle isn't empty before doing the checked cast. | |
281 if (that.IsEmpty()) return Local<T>(); | |
282 #endif | |
283 return Local<T>(T::Cast(*that)); | |
284 } | |
285 | |
286 template <class S> inline Local<S> As() { | |
287 return Local<S>::Cast(*this); | |
288 } | |
289 | |
290 /** Create a local handle for the content of another handle. | |
291 * The referee is kept alive by the local handle even when | |
292 * the original handle is destroyed/disposed. | |
293 */ | |
294 inline static Local<T> New(Handle<T> that); | |
295 }; | |
296 | |
297 | |
298 /** | |
299 * An object reference that is independent of any handle scope. Where | |
300 * a Local handle only lives as long as the HandleScope in which it was | |
301 * allocated, a Persistent handle remains valid until it is explicitly | |
302 * disposed. | |
303 * | |
304 * A persistent handle contains a reference to a storage cell within | |
305 * the v8 engine which holds an object value and which is updated by | |
306 * the garbage collector whenever the object is moved. A new storage | |
307 * cell can be created using Persistent::New and existing handles can | |
308 * be disposed using Persistent::Dispose. Since persistent handles | |
309 * are passed by value you may have many persistent handle objects | |
310 * that point to the same storage cell. For instance, if you pass a | |
311 * persistent handle as an argument to a function you will not get two | |
312 * different storage cells but rather two references to the same | |
313 * storage cell. | |
314 */ | |
315 template <class T> class Persistent : public Handle<T> { | |
316 public: | |
317 /** | |
318 * Creates an empty persistent handle that doesn't point to any | |
319 * storage cell. | |
320 */ | |
321 inline Persistent(); | |
322 | |
323 /** | |
324 * Creates a persistent handle for the same storage cell as the | |
325 * specified handle. This constructor allows you to pass persistent | |
326 * handles as arguments by value and to assign between persistent | |
327 * handles. However, attempting to assign between incompatible | |
328 * persistent handles, for instance from a Persistent<String> to a | |
329 * Persistent<Number> will cause a compile-time error. Assigning | |
330 * between compatible persistent handles, for instance assigning a | |
331 * Persistent<String> to a variable declared as Persistent<Value>, | |
332 * is allowed as String is a subclass of Value. | |
333 */ | |
334 template <class S> inline Persistent(Persistent<S> that) | |
335 : Handle<T>(reinterpret_cast<T*>(*that)) { | |
336 /** | |
337 * This check fails when trying to convert between incompatible | |
338 * handles. For example, converting from a Handle<String> to a | |
339 * Handle<Number>. | |
340 */ | |
341 TYPE_CHECK(T, S); | |
342 } | |
343 | |
344 template <class S> inline Persistent(S* that) : Handle<T>(that) { } | |
345 | |
346 /** | |
347 * "Casts" a plain handle which is known to be a persistent handle | |
348 * to a persistent handle. | |
349 */ | |
350 template <class S> explicit inline Persistent(Handle<S> that) | |
351 : Handle<T>(*that) { } | |
352 | |
353 template <class S> static inline Persistent<T> Cast(Persistent<S> that) { | |
354 #ifdef V8_ENABLE_CHECKS | |
355 // If we're going to perform the type check then we have to check | |
356 // that the handle isn't empty before doing the checked cast. | |
357 if (that.IsEmpty()) return Persistent<T>(); | |
358 #endif | |
359 return Persistent<T>(T::Cast(*that)); | |
360 } | |
361 | |
362 template <class S> inline Persistent<S> As() { | |
363 return Persistent<S>::Cast(*this); | |
364 } | |
365 | |
366 /** | |
367 * Creates a new persistent handle for an existing local or | |
368 * persistent handle. | |
369 */ | |
370 inline static Persistent<T> New(Handle<T> that); | |
371 | |
372 /** | |
373 * Releases the storage cell referenced by this persistent handle. | |
374 * Does not remove the reference to the cell from any handles. | |
375 * This handle's reference, and any other references to the storage | |
376 * cell remain and IsEmpty will still return false. | |
377 */ | |
378 inline void Dispose(); | |
379 | |
380 /** | |
381 * Make the reference to this object weak. When only weak handles | |
382 * refer to the object, the garbage collector will perform a | |
383 * callback to the given V8::WeakReferenceCallback function, passing | |
384 * it the object reference and the given parameters. | |
385 */ | |
386 inline void MakeWeak(void* parameters, WeakReferenceCallback callback); | |
387 | |
388 /** Clears the weak reference to this object.*/ | |
389 inline void ClearWeak(); | |
390 | |
391 /** | |
392 * Marks the reference to this object independent. Garbage collector | |
393 * is free to ignore any object groups containing this object. | |
394 * Weak callback for an independent handle should not | |
395 * assume that it will be preceded by a global GC prologue callback | |
396 * or followed by a global GC epilogue callback. | |
397 */ | |
398 inline void MarkIndependent(); | |
399 | |
400 /** | |
401 *Checks if the handle holds the only reference to an object. | |
402 */ | |
403 inline bool IsNearDeath() const; | |
404 | |
405 /** | |
406 * Returns true if the handle's reference is weak. | |
407 */ | |
408 inline bool IsWeak() const; | |
409 | |
410 /** | |
411 * Assigns a wrapper class ID to the handle. See RetainedObjectInfo | |
412 * interface description in v8-profiler.h for details. | |
413 */ | |
414 inline void SetWrapperClassId(uint16_t class_id); | |
415 | |
416 private: | |
417 friend class ImplementationUtilities; | |
418 friend class ObjectTemplate; | |
419 }; | |
420 | |
421 | |
422 /** | |
423 * A stack-allocated class that governs a number of local handles. | |
424 * After a handle scope has been created, all local handles will be | |
425 * allocated within that handle scope until either the handle scope is | |
426 * deleted or another handle scope is created. If there is already a | |
427 * handle scope and a new one is created, all allocations will take | |
428 * place in the new handle scope until it is deleted. After that, | |
429 * new handles will again be allocated in the original handle scope. | |
430 * | |
431 * After the handle scope of a local handle has been deleted the | |
432 * garbage collector will no longer track the object stored in the | |
433 * handle and may deallocate it. The behavior of accessing a handle | |
434 * for which the handle scope has been deleted is undefined. | |
435 */ | |
436 class V8EXPORT HandleScope { | |
437 public: | |
438 HandleScope(); | |
439 | |
440 ~HandleScope(); | |
441 | |
442 /** | |
443 * Closes the handle scope and returns the value as a handle in the | |
444 * previous scope, which is the new current scope after the call. | |
445 */ | |
446 template <class T> Local<T> Close(Handle<T> value); | |
447 | |
448 /** | |
449 * Counts the number of allocated handles. | |
450 */ | |
451 static int NumberOfHandles(); | |
452 | |
453 /** | |
454 * Creates a new handle with the given value. | |
455 */ | |
456 static internal::Object** CreateHandle(internal::Object* value); | |
457 // Faster version, uses HeapObject to obtain the current Isolate. | |
458 static internal::Object** CreateHandle(internal::HeapObject* value); | |
459 | |
460 private: | |
461 // Make it impossible to create heap-allocated or illegal handle | |
462 // scopes by disallowing certain operations. | |
463 HandleScope(const HandleScope&); | |
464 void operator=(const HandleScope&); | |
465 void* operator new(size_t size); | |
466 void operator delete(void*, size_t); | |
467 | |
468 // This Data class is accessible internally as HandleScopeData through a | |
469 // typedef in the ImplementationUtilities class. | |
470 class V8EXPORT Data { | |
471 public: | |
472 internal::Object** next; | |
473 internal::Object** limit; | |
474 int level; | |
475 inline void Initialize() { | |
476 next = limit = NULL; | |
477 level = 0; | |
478 } | |
479 }; | |
480 | |
481 void Leave(); | |
482 | |
483 internal::Isolate* isolate_; | |
484 internal::Object** prev_next_; | |
485 internal::Object** prev_limit_; | |
486 | |
487 // Allow for the active closing of HandleScopes which allows to pass a handle | |
488 // from the HandleScope being closed to the next top most HandleScope. | |
489 bool is_closed_; | |
490 internal::Object** RawClose(internal::Object** value); | |
491 | |
492 friend class ImplementationUtilities; | |
493 }; | |
494 | |
495 | |
496 // --- Special objects --- | |
497 | |
498 | |
499 /** | |
500 * The superclass of values and API object templates. | |
501 */ | |
502 class V8EXPORT Data { | |
503 private: | |
504 Data(); | |
505 }; | |
506 | |
507 | |
508 /** | |
509 * Pre-compilation data that can be associated with a script. This | |
510 * data can be calculated for a script in advance of actually | |
511 * compiling it, and can be stored between compilations. When script | |
512 * data is given to the compile method compilation will be faster. | |
513 */ | |
514 class V8EXPORT ScriptData { // NOLINT | |
515 public: | |
516 virtual ~ScriptData() { } | |
517 | |
518 /** | |
519 * Pre-compiles the specified script (context-independent). | |
520 * | |
521 * \param input Pointer to UTF-8 script source code. | |
522 * \param length Length of UTF-8 script source code. | |
523 */ | |
524 static ScriptData* PreCompile(const char* input, int length); | |
525 | |
526 /** | |
527 * Pre-compiles the specified script (context-independent). | |
528 * | |
529 * NOTE: Pre-compilation using this method cannot happen on another thread | |
530 * without using Lockers. | |
531 * | |
532 * \param source Script source code. | |
533 */ | |
534 static ScriptData* PreCompile(Handle<String> source); | |
535 | |
536 /** | |
537 * Load previous pre-compilation data. | |
538 * | |
539 * \param data Pointer to data returned by a call to Data() of a previous | |
540 * ScriptData. Ownership is not transferred. | |
541 * \param length Length of data. | |
542 */ | |
543 static ScriptData* New(const char* data, int length); | |
544 | |
545 /** | |
546 * Returns the length of Data(). | |
547 */ | |
548 virtual int Length() = 0; | |
549 | |
550 /** | |
551 * Returns a serialized representation of this ScriptData that can later be | |
552 * passed to New(). NOTE: Serialized data is platform-dependent. | |
553 */ | |
554 virtual const char* Data() = 0; | |
555 | |
556 /** | |
557 * Returns true if the source code could not be parsed. | |
558 */ | |
559 virtual bool HasError() = 0; | |
560 }; | |
561 | |
562 | |
563 /** | |
564 * The origin, within a file, of a script. | |
565 */ | |
566 class ScriptOrigin { | |
567 public: | |
568 inline ScriptOrigin( | |
569 Handle<Value> resource_name, | |
570 Handle<Integer> resource_line_offset = Handle<Integer>(), | |
571 Handle<Integer> resource_column_offset = Handle<Integer>()) | |
572 : resource_name_(resource_name), | |
573 resource_line_offset_(resource_line_offset), | |
574 resource_column_offset_(resource_column_offset) { } | |
575 inline Handle<Value> ResourceName() const; | |
576 inline Handle<Integer> ResourceLineOffset() const; | |
577 inline Handle<Integer> ResourceColumnOffset() const; | |
578 private: | |
579 Handle<Value> resource_name_; | |
580 Handle<Integer> resource_line_offset_; | |
581 Handle<Integer> resource_column_offset_; | |
582 }; | |
583 | |
584 | |
585 /** | |
586 * A compiled JavaScript script. | |
587 */ | |
588 class V8EXPORT Script { | |
589 public: | |
590 /** | |
591 * Compiles the specified script (context-independent). | |
592 * | |
593 * \param source Script source code. | |
594 * \param origin Script origin, owned by caller, no references are kept | |
595 * when New() returns | |
596 * \param pre_data Pre-parsing data, as obtained by ScriptData::PreCompile() | |
597 * using pre_data speeds compilation if it's done multiple times. | |
598 * Owned by caller, no references are kept when New() returns. | |
599 * \param script_data Arbitrary data associated with script. Using | |
600 * this has same effect as calling SetData(), but allows data to be | |
601 * available to compile event handlers. | |
602 * \return Compiled script object (context independent; when run it | |
603 * will use the currently entered context). | |
604 */ | |
605 static Local<Script> New(Handle<String> source, | |
606 ScriptOrigin* origin = NULL, | |
607 ScriptData* pre_data = NULL, | |
608 Handle<String> script_data = Handle<String>()); | |
609 | |
610 /** | |
611 * Compiles the specified script using the specified file name | |
612 * object (typically a string) as the script's origin. | |
613 * | |
614 * \param source Script source code. | |
615 * \param file_name file name object (typically a string) to be used | |
616 * as the script's origin. | |
617 * \return Compiled script object (context independent; when run it | |
618 * will use the currently entered context). | |
619 */ | |
620 static Local<Script> New(Handle<String> source, | |
621 Handle<Value> file_name); | |
622 | |
623 /** | |
624 * Compiles the specified script (bound to current context). | |
625 * | |
626 * \param source Script source code. | |
627 * \param origin Script origin, owned by caller, no references are kept | |
628 * when Compile() returns | |
629 * \param pre_data Pre-parsing data, as obtained by ScriptData::PreCompile() | |
630 * using pre_data speeds compilation if it's done multiple times. | |
631 * Owned by caller, no references are kept when Compile() returns. | |
632 * \param script_data Arbitrary data associated with script. Using | |
633 * this has same effect as calling SetData(), but makes data available | |
634 * earlier (i.e. to compile event handlers). | |
635 * \return Compiled script object, bound to the context that was active | |
636 * when this function was called. When run it will always use this | |
637 * context. | |
638 */ | |
639 static Local<Script> Compile(Handle<String> source, | |
640 ScriptOrigin* origin = NULL, | |
641 ScriptData* pre_data = NULL, | |
642 Handle<String> script_data = Handle<String>()); | |
643 | |
644 /** | |
645 * Compiles the specified script using the specified file name | |
646 * object (typically a string) as the script's origin. | |
647 * | |
648 * \param source Script source code. | |
649 * \param file_name File name to use as script's origin | |
650 * \param script_data Arbitrary data associated with script. Using | |
651 * this has same effect as calling SetData(), but makes data available | |
652 * earlier (i.e. to compile event handlers). | |
653 * \return Compiled script object, bound to the context that was active | |
654 * when this function was called. When run it will always use this | |
655 * context. | |
656 */ | |
657 static Local<Script> Compile(Handle<String> source, | |
658 Handle<Value> file_name, | |
659 Handle<String> script_data = Handle<String>()); | |
660 | |
661 /** | |
662 * Runs the script returning the resulting value. If the script is | |
663 * context independent (created using ::New) it will be run in the | |
664 * currently entered context. If it is context specific (created | |
665 * using ::Compile) it will be run in the context in which it was | |
666 * compiled. | |
667 */ | |
668 Local<Value> Run(); | |
669 | |
670 /** | |
671 * Returns the script id value. | |
672 */ | |
673 Local<Value> Id(); | |
674 | |
675 /** | |
676 * Associate an additional data object with the script. This is mainly used | |
677 * with the debugger as this data object is only available through the | |
678 * debugger API. | |
679 */ | |
680 void SetData(Handle<String> data); | |
681 }; | |
682 | |
683 | |
684 /** | |
685 * An error message. | |
686 */ | |
687 class V8EXPORT Message { | |
688 public: | |
689 Local<String> Get() const; | |
690 Local<String> GetSourceLine() const; | |
691 | |
692 /** | |
693 * Returns the resource name for the script from where the function causing | |
694 * the error originates. | |
695 */ | |
696 Handle<Value> GetScriptResourceName() const; | |
697 | |
698 /** | |
699 * Returns the resource data for the script from where the function causing | |
700 * the error originates. | |
701 */ | |
702 Handle<Value> GetScriptData() const; | |
703 | |
704 /** | |
705 * Exception stack trace. By default stack traces are not captured for | |
706 * uncaught exceptions. SetCaptureStackTraceForUncaughtExceptions allows | |
707 * to change this option. | |
708 */ | |
709 Handle<StackTrace> GetStackTrace() const; | |
710 | |
711 /** | |
712 * Returns the number, 1-based, of the line where the error occurred. | |
713 */ | |
714 int GetLineNumber() const; | |
715 | |
716 /** | |
717 * Returns the index within the script of the first character where | |
718 * the error occurred. | |
719 */ | |
720 int GetStartPosition() const; | |
721 | |
722 /** | |
723 * Returns the index within the script of the last character where | |
724 * the error occurred. | |
725 */ | |
726 int GetEndPosition() const; | |
727 | |
728 /** | |
729 * Returns the index within the line of the first character where | |
730 * the error occurred. | |
731 */ | |
732 int GetStartColumn() const; | |
733 | |
734 /** | |
735 * Returns the index within the line of the last character where | |
736 * the error occurred. | |
737 */ | |
738 int GetEndColumn() const; | |
739 | |
740 // TODO(1245381): Print to a string instead of on a FILE. | |
741 static void PrintCurrentStackTrace(FILE* out); | |
742 | |
743 static const int kNoLineNumberInfo = 0; | |
744 static const int kNoColumnInfo = 0; | |
745 }; | |
746 | |
747 | |
748 /** | |
749 * Representation of a JavaScript stack trace. The information collected is a | |
750 * snapshot of the execution stack and the information remains valid after | |
751 * execution continues. | |
752 */ | |
753 class V8EXPORT StackTrace { | |
754 public: | |
755 /** | |
756 * Flags that determine what information is placed captured for each | |
757 * StackFrame when grabbing the current stack trace. | |
758 */ | |
759 enum StackTraceOptions { | |
760 kLineNumber = 1, | |
761 kColumnOffset = 1 << 1 | kLineNumber, | |
762 kScriptName = 1 << 2, | |
763 kFunctionName = 1 << 3, | |
764 kIsEval = 1 << 4, | |
765 kIsConstructor = 1 << 5, | |
766 kScriptNameOrSourceURL = 1 << 6, | |
767 kOverview = kLineNumber | kColumnOffset | kScriptName | kFunctionName, | |
768 kDetailed = kOverview | kIsEval | kIsConstructor | kScriptNameOrSourceURL | |
769 }; | |
770 | |
771 /** | |
772 * Returns a StackFrame at a particular index. | |
773 */ | |
774 Local<StackFrame> GetFrame(uint32_t index) const; | |
775 | |
776 /** | |
777 * Returns the number of StackFrames. | |
778 */ | |
779 int GetFrameCount() const; | |
780 | |
781 /** | |
782 * Returns StackTrace as a v8::Array that contains StackFrame objects. | |
783 */ | |
784 Local<Array> AsArray(); | |
785 | |
786 /** | |
787 * Grab a snapshot of the current JavaScript execution stack. | |
788 * | |
789 * \param frame_limit The maximum number of stack frames we want to capture. | |
790 * \param options Enumerates the set of things we will capture for each | |
791 * StackFrame. | |
792 */ | |
793 static Local<StackTrace> CurrentStackTrace( | |
794 int frame_limit, | |
795 StackTraceOptions options = kOverview); | |
796 }; | |
797 | |
798 | |
799 /** | |
800 * A single JavaScript stack frame. | |
801 */ | |
802 class V8EXPORT StackFrame { | |
803 public: | |
804 /** | |
805 * Returns the number, 1-based, of the line for the associate function call. | |
806 * This method will return Message::kNoLineNumberInfo if it is unable to | |
807 * retrieve the line number, or if kLineNumber was not passed as an option | |
808 * when capturing the StackTrace. | |
809 */ | |
810 int GetLineNumber() const; | |
811 | |
812 /** | |
813 * Returns the 1-based column offset on the line for the associated function | |
814 * call. | |
815 * This method will return Message::kNoColumnInfo if it is unable to retrieve | |
816 * the column number, or if kColumnOffset was not passed as an option when | |
817 * capturing the StackTrace. | |
818 */ | |
819 int GetColumn() const; | |
820 | |
821 /** | |
822 * Returns the name of the resource that contains the script for the | |
823 * function for this StackFrame. | |
824 */ | |
825 Local<String> GetScriptName() const; | |
826 | |
827 /** | |
828 * Returns the name of the resource that contains the script for the | |
829 * function for this StackFrame or sourceURL value if the script name | |
830 * is undefined and its source ends with //@ sourceURL=... string. | |
831 */ | |
832 Local<String> GetScriptNameOrSourceURL() const; | |
833 | |
834 /** | |
835 * Returns the name of the function associated with this stack frame. | |
836 */ | |
837 Local<String> GetFunctionName() const; | |
838 | |
839 /** | |
840 * Returns whether or not the associated function is compiled via a call to | |
841 * eval(). | |
842 */ | |
843 bool IsEval() const; | |
844 | |
845 /** | |
846 * Returns whether or not the associated function is called as a | |
847 * constructor via "new". | |
848 */ | |
849 bool IsConstructor() const; | |
850 }; | |
851 | |
852 | |
853 // --- Value --- | |
854 | |
855 | |
856 /** | |
857 * The superclass of all JavaScript values and objects. | |
858 */ | |
859 class Value : public Data { | |
860 public: | |
861 /** | |
862 * Returns true if this value is the undefined value. See ECMA-262 | |
863 * 4.3.10. | |
864 */ | |
865 V8EXPORT bool IsUndefined() const; | |
866 | |
867 /** | |
868 * Returns true if this value is the null value. See ECMA-262 | |
869 * 4.3.11. | |
870 */ | |
871 V8EXPORT bool IsNull() const; | |
872 | |
873 /** | |
874 * Returns true if this value is true. | |
875 */ | |
876 V8EXPORT bool IsTrue() const; | |
877 | |
878 /** | |
879 * Returns true if this value is false. | |
880 */ | |
881 V8EXPORT bool IsFalse() const; | |
882 | |
883 /** | |
884 * Returns true if this value is an instance of the String type. | |
885 * See ECMA-262 8.4. | |
886 */ | |
887 inline bool IsString() const; | |
888 | |
889 /** | |
890 * Returns true if this value is a function. | |
891 */ | |
892 V8EXPORT bool IsFunction() const; | |
893 | |
894 /** | |
895 * Returns true if this value is an array. | |
896 */ | |
897 V8EXPORT bool IsArray() const; | |
898 | |
899 /** | |
900 * Returns true if this value is an object. | |
901 */ | |
902 V8EXPORT bool IsObject() const; | |
903 | |
904 /** | |
905 * Returns true if this value is boolean. | |
906 */ | |
907 V8EXPORT bool IsBoolean() const; | |
908 | |
909 /** | |
910 * Returns true if this value is a number. | |
911 */ | |
912 V8EXPORT bool IsNumber() const; | |
913 | |
914 /** | |
915 * Returns true if this value is external. | |
916 */ | |
917 V8EXPORT bool IsExternal() const; | |
918 | |
919 /** | |
920 * Returns true if this value is a 32-bit signed integer. | |
921 */ | |
922 V8EXPORT bool IsInt32() const; | |
923 | |
924 /** | |
925 * Returns true if this value is a 32-bit unsigned integer. | |
926 */ | |
927 V8EXPORT bool IsUint32() const; | |
928 | |
929 /** | |
930 * Returns true if this value is a Date. | |
931 */ | |
932 V8EXPORT bool IsDate() const; | |
933 | |
934 /** | |
935 * Returns true if this value is a Boolean object. | |
936 */ | |
937 V8EXPORT bool IsBooleanObject() const; | |
938 | |
939 /** | |
940 * Returns true if this value is a Number object. | |
941 */ | |
942 V8EXPORT bool IsNumberObject() const; | |
943 | |
944 /** | |
945 * Returns true if this value is a String object. | |
946 */ | |
947 V8EXPORT bool IsStringObject() const; | |
948 | |
949 /** | |
950 * Returns true if this value is a NativeError. | |
951 */ | |
952 V8EXPORT bool IsNativeError() const; | |
953 | |
954 /** | |
955 * Returns true if this value is a RegExp. | |
956 */ | |
957 V8EXPORT bool IsRegExp() const; | |
958 | |
959 V8EXPORT Local<Boolean> ToBoolean() const; | |
960 V8EXPORT Local<Number> ToNumber() const; | |
961 V8EXPORT Local<String> ToString() const; | |
962 V8EXPORT Local<String> ToDetailString() const; | |
963 V8EXPORT Local<Object> ToObject() const; | |
964 V8EXPORT Local<Integer> ToInteger() const; | |
965 V8EXPORT Local<Uint32> ToUint32() const; | |
966 V8EXPORT Local<Int32> ToInt32() const; | |
967 | |
968 /** | |
969 * Attempts to convert a string to an array index. | |
970 * Returns an empty handle if the conversion fails. | |
971 */ | |
972 V8EXPORT Local<Uint32> ToArrayIndex() const; | |
973 | |
974 V8EXPORT bool BooleanValue() const; | |
975 V8EXPORT double NumberValue() const; | |
976 V8EXPORT int64_t IntegerValue() const; | |
977 V8EXPORT uint32_t Uint32Value() const; | |
978 V8EXPORT int32_t Int32Value() const; | |
979 | |
980 /** JS == */ | |
981 V8EXPORT bool Equals(Handle<Value> that) const; | |
982 V8EXPORT bool StrictEquals(Handle<Value> that) const; | |
983 | |
984 private: | |
985 inline bool QuickIsString() const; | |
986 V8EXPORT bool FullIsString() const; | |
987 }; | |
988 | |
989 | |
990 /** | |
991 * The superclass of primitive values. See ECMA-262 4.3.2. | |
992 */ | |
993 class Primitive : public Value { }; | |
994 | |
995 | |
996 /** | |
997 * A primitive boolean value (ECMA-262, 4.3.14). Either the true | |
998 * or false value. | |
999 */ | |
1000 class Boolean : public Primitive { | |
1001 public: | |
1002 V8EXPORT bool Value() const; | |
1003 static inline Handle<Boolean> New(bool value); | |
1004 }; | |
1005 | |
1006 | |
1007 /** | |
1008 * A JavaScript string value (ECMA-262, 4.3.17). | |
1009 */ | |
1010 class String : public Primitive { | |
1011 public: | |
1012 /** | |
1013 * Returns the number of characters in this string. | |
1014 */ | |
1015 V8EXPORT int Length() const; | |
1016 | |
1017 /** | |
1018 * Returns the number of bytes in the UTF-8 encoded | |
1019 * representation of this string. | |
1020 */ | |
1021 V8EXPORT int Utf8Length() const; | |
1022 | |
1023 /** | |
1024 * Write the contents of the string to an external buffer. | |
1025 * If no arguments are given, expects the buffer to be large | |
1026 * enough to hold the entire string and NULL terminator. Copies | |
1027 * the contents of the string and the NULL terminator into the | |
1028 * buffer. | |
1029 * | |
1030 * WriteUtf8 will not write partial UTF-8 sequences, preferring to stop | |
1031 * before the end of the buffer. | |
1032 * | |
1033 * Copies up to length characters into the output buffer. | |
1034 * Only null-terminates if there is enough space in the buffer. | |
1035 * | |
1036 * \param buffer The buffer into which the string will be copied. | |
1037 * \param start The starting position within the string at which | |
1038 * copying begins. | |
1039 * \param length The number of characters to copy from the string. For | |
1040 * WriteUtf8 the number of bytes in the buffer. | |
1041 * \param nchars_ref The number of characters written, can be NULL. | |
1042 * \param options Various options that might affect performance of this or | |
1043 * subsequent operations. | |
1044 * \return The number of characters copied to the buffer excluding the null | |
1045 * terminator. For WriteUtf8: The number of bytes copied to the buffer | |
1046 * including the null terminator (if written). | |
1047 */ | |
1048 enum WriteOptions { | |
1049 NO_OPTIONS = 0, | |
1050 HINT_MANY_WRITES_EXPECTED = 1, | |
1051 NO_NULL_TERMINATION = 2 | |
1052 }; | |
1053 | |
1054 // 16-bit character codes. | |
1055 V8EXPORT int Write(uint16_t* buffer, | |
1056 int start = 0, | |
1057 int length = -1, | |
1058 int options = NO_OPTIONS) const; | |
1059 // ASCII characters. | |
1060 V8EXPORT int WriteAscii(char* buffer, | |
1061 int start = 0, | |
1062 int length = -1, | |
1063 int options = NO_OPTIONS) const; | |
1064 // UTF-8 encoded characters. | |
1065 V8EXPORT int WriteUtf8(char* buffer, | |
1066 int length = -1, | |
1067 int* nchars_ref = NULL, | |
1068 int options = NO_OPTIONS) const; | |
1069 | |
1070 /** | |
1071 * A zero length string. | |
1072 */ | |
1073 V8EXPORT static v8::Local<v8::String> Empty(); | |
1074 | |
1075 /** | |
1076 * Returns true if the string is external | |
1077 */ | |
1078 V8EXPORT bool IsExternal() const; | |
1079 | |
1080 /** | |
1081 * Returns true if the string is both external and ASCII | |
1082 */ | |
1083 V8EXPORT bool IsExternalAscii() const; | |
1084 | |
1085 class V8EXPORT ExternalStringResourceBase { // NOLINT | |
1086 public: | |
1087 virtual ~ExternalStringResourceBase() {} | |
1088 | |
1089 protected: | |
1090 ExternalStringResourceBase() {} | |
1091 | |
1092 /** | |
1093 * Internally V8 will call this Dispose method when the external string | |
1094 * resource is no longer needed. The default implementation will use the | |
1095 * delete operator. This method can be overridden in subclasses to | |
1096 * control how allocated external string resources are disposed. | |
1097 */ | |
1098 virtual void Dispose() { delete this; } | |
1099 | |
1100 private: | |
1101 // Disallow copying and assigning. | |
1102 ExternalStringResourceBase(const ExternalStringResourceBase&); | |
1103 void operator=(const ExternalStringResourceBase&); | |
1104 | |
1105 friend class v8::internal::Heap; | |
1106 }; | |
1107 | |
1108 /** | |
1109 * An ExternalStringResource is a wrapper around a two-byte string | |
1110 * buffer that resides outside V8's heap. Implement an | |
1111 * ExternalStringResource to manage the life cycle of the underlying | |
1112 * buffer. Note that the string data must be immutable. | |
1113 */ | |
1114 class V8EXPORT ExternalStringResource | |
1115 : public ExternalStringResourceBase { | |
1116 public: | |
1117 /** | |
1118 * Override the destructor to manage the life cycle of the underlying | |
1119 * buffer. | |
1120 */ | |
1121 virtual ~ExternalStringResource() {} | |
1122 | |
1123 /** | |
1124 * The string data from the underlying buffer. | |
1125 */ | |
1126 virtual const uint16_t* data() const = 0; | |
1127 | |
1128 /** | |
1129 * The length of the string. That is, the number of two-byte characters. | |
1130 */ | |
1131 virtual size_t length() const = 0; | |
1132 | |
1133 protected: | |
1134 ExternalStringResource() {} | |
1135 }; | |
1136 | |
1137 /** | |
1138 * An ExternalAsciiStringResource is a wrapper around an ASCII | |
1139 * string buffer that resides outside V8's heap. Implement an | |
1140 * ExternalAsciiStringResource to manage the life cycle of the | |
1141 * underlying buffer. Note that the string data must be immutable | |
1142 * and that the data must be strict (7-bit) ASCII, not Latin-1 or | |
1143 * UTF-8, which would require special treatment internally in the | |
1144 * engine and, in the case of UTF-8, do not allow efficient indexing. | |
1145 * Use String::New or convert to 16 bit data for non-ASCII. | |
1146 */ | |
1147 | |
1148 class V8EXPORT ExternalAsciiStringResource | |
1149 : public ExternalStringResourceBase { | |
1150 public: | |
1151 /** | |
1152 * Override the destructor to manage the life cycle of the underlying | |
1153 * buffer. | |
1154 */ | |
1155 virtual ~ExternalAsciiStringResource() {} | |
1156 /** The string data from the underlying buffer.*/ | |
1157 virtual const char* data() const = 0; | |
1158 /** The number of ASCII characters in the string.*/ | |
1159 virtual size_t length() const = 0; | |
1160 protected: | |
1161 ExternalAsciiStringResource() {} | |
1162 }; | |
1163 | |
1164 /** | |
1165 * Get the ExternalStringResource for an external string. Returns | |
1166 * NULL if IsExternal() doesn't return true. | |
1167 */ | |
1168 inline ExternalStringResource* GetExternalStringResource() const; | |
1169 | |
1170 /** | |
1171 * Get the ExternalAsciiStringResource for an external ASCII string. | |
1172 * Returns NULL if IsExternalAscii() doesn't return true. | |
1173 */ | |
1174 V8EXPORT const ExternalAsciiStringResource* GetExternalAsciiStringResource() | |
1175 const; | |
1176 | |
1177 static inline String* Cast(v8::Value* obj); | |
1178 | |
1179 /** | |
1180 * Allocates a new string from either UTF-8 encoded or ASCII data. | |
1181 * The second parameter 'length' gives the buffer length. | |
1182 * If the data is UTF-8 encoded, the caller must | |
1183 * be careful to supply the length parameter. | |
1184 * If it is not given, the function calls | |
1185 * 'strlen' to determine the buffer length, it might be | |
1186 * wrong if 'data' contains a null character. | |
1187 */ | |
1188 V8EXPORT static Local<String> New(const char* data, int length = -1); | |
1189 | |
1190 /** Allocates a new string from 16-bit character codes.*/ | |
1191 V8EXPORT static Local<String> New(const uint16_t* data, int length = -1); | |
1192 | |
1193 /** Creates a symbol. Returns one if it exists already.*/ | |
1194 V8EXPORT static Local<String> NewSymbol(const char* data, int length = -1); | |
1195 | |
1196 /** | |
1197 * Creates a new string by concatenating the left and the right strings | |
1198 * passed in as parameters. | |
1199 */ | |
1200 V8EXPORT static Local<String> Concat(Handle<String> left, | |
1201 Handle<String> right); | |
1202 | |
1203 /** | |
1204 * Creates a new external string using the data defined in the given | |
1205 * resource. When the external string is no longer live on V8's heap the | |
1206 * resource will be disposed by calling its Dispose method. The caller of | |
1207 * this function should not otherwise delete or modify the resource. Neither | |
1208 * should the underlying buffer be deallocated or modified except through the | |
1209 * destructor of the external string resource. | |
1210 */ | |
1211 V8EXPORT static Local<String> NewExternal(ExternalStringResource* resource); | |
1212 | |
1213 /** | |
1214 * Associate an external string resource with this string by transforming it | |
1215 * in place so that existing references to this string in the JavaScript heap | |
1216 * will use the external string resource. The external string resource's | |
1217 * character contents need to be equivalent to this string. | |
1218 * Returns true if the string has been changed to be an external string. | |
1219 * The string is not modified if the operation fails. See NewExternal for | |
1220 * information on the lifetime of the resource. | |
1221 */ | |
1222 V8EXPORT bool MakeExternal(ExternalStringResource* resource); | |
1223 | |
1224 /** | |
1225 * Creates a new external string using the ASCII data defined in the given | |
1226 * resource. When the external string is no longer live on V8's heap the | |
1227 * resource will be disposed by calling its Dispose method. The caller of | |
1228 * this function should not otherwise delete or modify the resource. Neither | |
1229 * should the underlying buffer be deallocated or modified except through the | |
1230 * destructor of the external string resource. | |
1231 */ | |
1232 V8EXPORT static Local<String> NewExternal( | |
1233 ExternalAsciiStringResource* resource); | |
1234 | |
1235 /** | |
1236 * Associate an external string resource with this string by transforming it | |
1237 * in place so that existing references to this string in the JavaScript heap | |
1238 * will use the external string resource. The external string resource's | |
1239 * character contents need to be equivalent to this string. | |
1240 * Returns true if the string has been changed to be an external string. | |
1241 * The string is not modified if the operation fails. See NewExternal for | |
1242 * information on the lifetime of the resource. | |
1243 */ | |
1244 V8EXPORT bool MakeExternal(ExternalAsciiStringResource* resource); | |
1245 | |
1246 /** | |
1247 * Returns true if this string can be made external. | |
1248 */ | |
1249 V8EXPORT bool CanMakeExternal(); | |
1250 | |
1251 /** Creates an undetectable string from the supplied ASCII or UTF-8 data.*/ | |
1252 V8EXPORT static Local<String> NewUndetectable(const char* data, | |
1253 int length = -1); | |
1254 | |
1255 /** Creates an undetectable string from the supplied 16-bit character codes.*/ | |
1256 V8EXPORT static Local<String> NewUndetectable(const uint16_t* data, | |
1257 int length = -1); | |
1258 | |
1259 /** | |
1260 * Converts an object to a UTF-8-encoded character array. Useful if | |
1261 * you want to print the object. If conversion to a string fails | |
1262 * (e.g. due to an exception in the toString() method of the object) | |
1263 * then the length() method returns 0 and the * operator returns | |
1264 * NULL. | |
1265 */ | |
1266 class V8EXPORT Utf8Value { | |
1267 public: | |
1268 explicit Utf8Value(Handle<v8::Value> obj); | |
1269 ~Utf8Value(); | |
1270 char* operator*() { return str_; } | |
1271 const char* operator*() const { return str_; } | |
1272 int length() const { return length_; } | |
1273 private: | |
1274 char* str_; | |
1275 int length_; | |
1276 | |
1277 // Disallow copying and assigning. | |
1278 Utf8Value(const Utf8Value&); | |
1279 void operator=(const Utf8Value&); | |
1280 }; | |
1281 | |
1282 /** | |
1283 * Converts an object to an ASCII string. | |
1284 * Useful if you want to print the object. | |
1285 * If conversion to a string fails (eg. due to an exception in the toString() | |
1286 * method of the object) then the length() method returns 0 and the * operator | |
1287 * returns NULL. | |
1288 */ | |
1289 class V8EXPORT AsciiValue { | |
1290 public: | |
1291 explicit AsciiValue(Handle<v8::Value> obj); | |
1292 ~AsciiValue(); | |
1293 char* operator*() { return str_; } | |
1294 const char* operator*() const { return str_; } | |
1295 int length() const { return length_; } | |
1296 private: | |
1297 char* str_; | |
1298 int length_; | |
1299 | |
1300 // Disallow copying and assigning. | |
1301 AsciiValue(const AsciiValue&); | |
1302 void operator=(const AsciiValue&); | |
1303 }; | |
1304 | |
1305 /** | |
1306 * Converts an object to a two-byte string. | |
1307 * If conversion to a string fails (eg. due to an exception in the toString() | |
1308 * method of the object) then the length() method returns 0 and the * operator | |
1309 * returns NULL. | |
1310 */ | |
1311 class V8EXPORT Value { | |
1312 public: | |
1313 explicit Value(Handle<v8::Value> obj); | |
1314 ~Value(); | |
1315 uint16_t* operator*() { return str_; } | |
1316 const uint16_t* operator*() const { return str_; } | |
1317 int length() const { return length_; } | |
1318 private: | |
1319 uint16_t* str_; | |
1320 int length_; | |
1321 | |
1322 // Disallow copying and assigning. | |
1323 Value(const Value&); | |
1324 void operator=(const Value&); | |
1325 }; | |
1326 | |
1327 private: | |
1328 V8EXPORT void VerifyExternalStringResource(ExternalStringResource* val) const; | |
1329 V8EXPORT static void CheckCast(v8::Value* obj); | |
1330 }; | |
1331 | |
1332 | |
1333 /** | |
1334 * A JavaScript number value (ECMA-262, 4.3.20) | |
1335 */ | |
1336 class Number : public Primitive { | |
1337 public: | |
1338 V8EXPORT double Value() const; | |
1339 V8EXPORT static Local<Number> New(double value); | |
1340 static inline Number* Cast(v8::Value* obj); | |
1341 private: | |
1342 V8EXPORT Number(); | |
1343 V8EXPORT static void CheckCast(v8::Value* obj); | |
1344 }; | |
1345 | |
1346 | |
1347 /** | |
1348 * A JavaScript value representing a signed integer. | |
1349 */ | |
1350 class Integer : public Number { | |
1351 public: | |
1352 V8EXPORT static Local<Integer> New(int32_t value); | |
1353 V8EXPORT static Local<Integer> NewFromUnsigned(uint32_t value); | |
1354 V8EXPORT int64_t Value() const; | |
1355 static inline Integer* Cast(v8::Value* obj); | |
1356 private: | |
1357 V8EXPORT Integer(); | |
1358 V8EXPORT static void CheckCast(v8::Value* obj); | |
1359 }; | |
1360 | |
1361 | |
1362 /** | |
1363 * A JavaScript value representing a 32-bit signed integer. | |
1364 */ | |
1365 class Int32 : public Integer { | |
1366 public: | |
1367 V8EXPORT int32_t Value() const; | |
1368 private: | |
1369 V8EXPORT Int32(); | |
1370 }; | |
1371 | |
1372 | |
1373 /** | |
1374 * A JavaScript value representing a 32-bit unsigned integer. | |
1375 */ | |
1376 class Uint32 : public Integer { | |
1377 public: | |
1378 V8EXPORT uint32_t Value() const; | |
1379 private: | |
1380 V8EXPORT Uint32(); | |
1381 }; | |
1382 | |
1383 | |
1384 enum PropertyAttribute { | |
1385 None = 0, | |
1386 ReadOnly = 1 << 0, | |
1387 DontEnum = 1 << 1, | |
1388 DontDelete = 1 << 2 | |
1389 }; | |
1390 | |
1391 enum ExternalArrayType { | |
1392 kExternalByteArray = 1, | |
1393 kExternalUnsignedByteArray, | |
1394 kExternalShortArray, | |
1395 kExternalUnsignedShortArray, | |
1396 kExternalIntArray, | |
1397 kExternalUnsignedIntArray, | |
1398 kExternalFloatArray, | |
1399 kExternalDoubleArray, | |
1400 kExternalPixelArray | |
1401 }; | |
1402 | |
1403 /** | |
1404 * Accessor[Getter|Setter] are used as callback functions when | |
1405 * setting|getting a particular property. See Object and ObjectTemplate's | |
1406 * method SetAccessor. | |
1407 */ | |
1408 typedef Handle<Value> (*AccessorGetter)(Local<String> property, | |
1409 const AccessorInfo& info); | |
1410 | |
1411 | |
1412 typedef void (*AccessorSetter)(Local<String> property, | |
1413 Local<Value> value, | |
1414 const AccessorInfo& info); | |
1415 | |
1416 | |
1417 /** | |
1418 * Access control specifications. | |
1419 * | |
1420 * Some accessors should be accessible across contexts. These | |
1421 * accessors have an explicit access control parameter which specifies | |
1422 * the kind of cross-context access that should be allowed. | |
1423 * | |
1424 * Additionally, for security, accessors can prohibit overwriting by | |
1425 * accessors defined in JavaScript. For objects that have such | |
1426 * accessors either locally or in their prototype chain it is not | |
1427 * possible to overwrite the accessor by using __defineGetter__ or | |
1428 * __defineSetter__ from JavaScript code. | |
1429 */ | |
1430 enum AccessControl { | |
1431 DEFAULT = 0, | |
1432 ALL_CAN_READ = 1, | |
1433 ALL_CAN_WRITE = 1 << 1, | |
1434 PROHIBITS_OVERWRITING = 1 << 2 | |
1435 }; | |
1436 | |
1437 | |
1438 /** | |
1439 * A JavaScript object (ECMA-262, 4.3.3) | |
1440 */ | |
1441 class Object : public Value { | |
1442 public: | |
1443 V8EXPORT bool Set(Handle<Value> key, | |
1444 Handle<Value> value, | |
1445 PropertyAttribute attribs = None); | |
1446 | |
1447 V8EXPORT bool Set(uint32_t index, | |
1448 Handle<Value> value); | |
1449 | |
1450 // Sets a local property on this object bypassing interceptors and | |
1451 // overriding accessors or read-only properties. | |
1452 // | |
1453 // Note that if the object has an interceptor the property will be set | |
1454 // locally, but since the interceptor takes precedence the local property | |
1455 // will only be returned if the interceptor doesn't return a value. | |
1456 // | |
1457 // Note also that this only works for named properties. | |
1458 V8EXPORT bool ForceSet(Handle<Value> key, | |
1459 Handle<Value> value, | |
1460 PropertyAttribute attribs = None); | |
1461 | |
1462 V8EXPORT Local<Value> Get(Handle<Value> key); | |
1463 | |
1464 V8EXPORT Local<Value> Get(uint32_t index); | |
1465 | |
1466 /** | |
1467 * Gets the property attributes of a property which can be None or | |
1468 * any combination of ReadOnly, DontEnum and DontDelete. Returns | |
1469 * None when the property doesn't exist. | |
1470 */ | |
1471 V8EXPORT PropertyAttribute GetPropertyAttributes(Handle<Value> key); | |
1472 | |
1473 // TODO(1245389): Replace the type-specific versions of these | |
1474 // functions with generic ones that accept a Handle<Value> key. | |
1475 V8EXPORT bool Has(Handle<String> key); | |
1476 | |
1477 V8EXPORT bool Delete(Handle<String> key); | |
1478 | |
1479 // Delete a property on this object bypassing interceptors and | |
1480 // ignoring dont-delete attributes. | |
1481 V8EXPORT bool ForceDelete(Handle<Value> key); | |
1482 | |
1483 V8EXPORT bool Has(uint32_t index); | |
1484 | |
1485 V8EXPORT bool Delete(uint32_t index); | |
1486 | |
1487 V8EXPORT bool SetAccessor(Handle<String> name, | |
1488 AccessorGetter getter, | |
1489 AccessorSetter setter = 0, | |
1490 Handle<Value> data = Handle<Value>(), | |
1491 AccessControl settings = DEFAULT, | |
1492 PropertyAttribute attribute = None); | |
1493 | |
1494 /** | |
1495 * Returns an array containing the names of the enumerable properties | |
1496 * of this object, including properties from prototype objects. The | |
1497 * array returned by this method contains the same values as would | |
1498 * be enumerated by a for-in statement over this object. | |
1499 */ | |
1500 V8EXPORT Local<Array> GetPropertyNames(); | |
1501 | |
1502 /** | |
1503 * This function has the same functionality as GetPropertyNames but | |
1504 * the returned array doesn't contain the names of properties from | |
1505 * prototype objects. | |
1506 */ | |
1507 V8EXPORT Local<Array> GetOwnPropertyNames(); | |
1508 | |
1509 /** | |
1510 * Get the prototype object. This does not skip objects marked to | |
1511 * be skipped by __proto__ and it does not consult the security | |
1512 * handler. | |
1513 */ | |
1514 V8EXPORT Local<Value> GetPrototype(); | |
1515 | |
1516 /** | |
1517 * Set the prototype object. This does not skip objects marked to | |
1518 * be skipped by __proto__ and it does not consult the security | |
1519 * handler. | |
1520 */ | |
1521 V8EXPORT bool SetPrototype(Handle<Value> prototype); | |
1522 | |
1523 /** | |
1524 * Finds an instance of the given function template in the prototype | |
1525 * chain. | |
1526 */ | |
1527 V8EXPORT Local<Object> FindInstanceInPrototypeChain( | |
1528 Handle<FunctionTemplate> tmpl); | |
1529 | |
1530 /** | |
1531 * Call builtin Object.prototype.toString on this object. | |
1532 * This is different from Value::ToString() that may call | |
1533 * user-defined toString function. This one does not. | |
1534 */ | |
1535 V8EXPORT Local<String> ObjectProtoToString(); | |
1536 | |
1537 /** | |
1538 * Returns the name of the function invoked as a constructor for this object. | |
1539 */ | |
1540 V8EXPORT Local<String> GetConstructorName(); | |
1541 | |
1542 /** Gets the number of internal fields for this Object. */ | |
1543 V8EXPORT int InternalFieldCount(); | |
1544 /** Gets the value in an internal field. */ | |
1545 inline Local<Value> GetInternalField(int index); | |
1546 /** Sets the value in an internal field. */ | |
1547 V8EXPORT void SetInternalField(int index, Handle<Value> value); | |
1548 | |
1549 /** Gets a native pointer from an internal field. */ | |
1550 inline void* GetPointerFromInternalField(int index); | |
1551 | |
1552 /** Sets a native pointer in an internal field. */ | |
1553 V8EXPORT void SetPointerInInternalField(int index, void* value); | |
1554 | |
1555 // Testers for local properties. | |
1556 V8EXPORT bool HasOwnProperty(Handle<String> key); | |
1557 V8EXPORT bool HasRealNamedProperty(Handle<String> key); | |
1558 V8EXPORT bool HasRealIndexedProperty(uint32_t index); | |
1559 V8EXPORT bool HasRealNamedCallbackProperty(Handle<String> key); | |
1560 | |
1561 /** | |
1562 * If result.IsEmpty() no real property was located in the prototype chain. | |
1563 * This means interceptors in the prototype chain are not called. | |
1564 */ | |
1565 V8EXPORT Local<Value> GetRealNamedPropertyInPrototypeChain( | |
1566 Handle<String> key); | |
1567 | |
1568 /** | |
1569 * If result.IsEmpty() no real property was located on the object or | |
1570 * in the prototype chain. | |
1571 * This means interceptors in the prototype chain are not called. | |
1572 */ | |
1573 V8EXPORT Local<Value> GetRealNamedProperty(Handle<String> key); | |
1574 | |
1575 /** Tests for a named lookup interceptor.*/ | |
1576 V8EXPORT bool HasNamedLookupInterceptor(); | |
1577 | |
1578 /** Tests for an index lookup interceptor.*/ | |
1579 V8EXPORT bool HasIndexedLookupInterceptor(); | |
1580 | |
1581 /** | |
1582 * Turns on access check on the object if the object is an instance of | |
1583 * a template that has access check callbacks. If an object has no | |
1584 * access check info, the object cannot be accessed by anyone. | |
1585 */ | |
1586 V8EXPORT void TurnOnAccessCheck(); | |
1587 | |
1588 /** | |
1589 * Returns the identity hash for this object. The current implementation | |
1590 * uses a hidden property on the object to store the identity hash. | |
1591 * | |
1592 * The return value will never be 0. Also, it is not guaranteed to be | |
1593 * unique. | |
1594 */ | |
1595 V8EXPORT int GetIdentityHash(); | |
1596 | |
1597 /** | |
1598 * Access hidden properties on JavaScript objects. These properties are | |
1599 * hidden from the executing JavaScript and only accessible through the V8 | |
1600 * C++ API. Hidden properties introduced by V8 internally (for example the | |
1601 * identity hash) are prefixed with "v8::". | |
1602 */ | |
1603 V8EXPORT bool SetHiddenValue(Handle<String> key, Handle<Value> value); | |
1604 V8EXPORT Local<Value> GetHiddenValue(Handle<String> key); | |
1605 V8EXPORT bool DeleteHiddenValue(Handle<String> key); | |
1606 | |
1607 /** | |
1608 * Returns true if this is an instance of an api function (one | |
1609 * created from a function created from a function template) and has | |
1610 * been modified since it was created. Note that this method is | |
1611 * conservative and may return true for objects that haven't actually | |
1612 * been modified. | |
1613 */ | |
1614 V8EXPORT bool IsDirty(); | |
1615 | |
1616 /** | |
1617 * Clone this object with a fast but shallow copy. Values will point | |
1618 * to the same values as the original object. | |
1619 */ | |
1620 V8EXPORT Local<Object> Clone(); | |
1621 | |
1622 /** | |
1623 * Returns the context in which the object was created. | |
1624 */ | |
1625 V8EXPORT Local<Context> CreationContext(); | |
1626 | |
1627 /** | |
1628 * Set the backing store of the indexed properties to be managed by the | |
1629 * embedding layer. Access to the indexed properties will follow the rules | |
1630 * spelled out in CanvasPixelArray. | |
1631 * Note: The embedding program still owns the data and needs to ensure that | |
1632 * the backing store is preserved while V8 has a reference. | |
1633 */ | |
1634 V8EXPORT void SetIndexedPropertiesToPixelData(uint8_t* data, int length); | |
1635 V8EXPORT bool HasIndexedPropertiesInPixelData(); | |
1636 V8EXPORT uint8_t* GetIndexedPropertiesPixelData(); | |
1637 V8EXPORT int GetIndexedPropertiesPixelDataLength(); | |
1638 | |
1639 /** | |
1640 * Set the backing store of the indexed properties to be managed by the | |
1641 * embedding layer. Access to the indexed properties will follow the rules | |
1642 * spelled out for the CanvasArray subtypes in the WebGL specification. | |
1643 * Note: The embedding program still owns the data and needs to ensure that | |
1644 * the backing store is preserved while V8 has a reference. | |
1645 */ | |
1646 V8EXPORT void SetIndexedPropertiesToExternalArrayData( | |
1647 void* data, | |
1648 ExternalArrayType array_type, | |
1649 int number_of_elements); | |
1650 V8EXPORT bool HasIndexedPropertiesInExternalArrayData(); | |
1651 V8EXPORT void* GetIndexedPropertiesExternalArrayData(); | |
1652 V8EXPORT ExternalArrayType GetIndexedPropertiesExternalArrayDataType(); | |
1653 V8EXPORT int GetIndexedPropertiesExternalArrayDataLength(); | |
1654 | |
1655 /** | |
1656 * Checks whether a callback is set by the | |
1657 * ObjectTemplate::SetCallAsFunctionHandler method. | |
1658 * When an Object is callable this method returns true. | |
1659 */ | |
1660 V8EXPORT bool IsCallable(); | |
1661 | |
1662 /** | |
1663 * Call an Object as a function if a callback is set by the | |
1664 * ObjectTemplate::SetCallAsFunctionHandler method. | |
1665 */ | |
1666 V8EXPORT Local<Value> CallAsFunction(Handle<Object> recv, | |
1667 int argc, | |
1668 Handle<Value> argv[]); | |
1669 | |
1670 /** | |
1671 * Call an Object as a constructor if a callback is set by the | |
1672 * ObjectTemplate::SetCallAsFunctionHandler method. | |
1673 * Note: This method behaves like the Function::NewInstance method. | |
1674 */ | |
1675 V8EXPORT Local<Value> CallAsConstructor(int argc, | |
1676 Handle<Value> argv[]); | |
1677 | |
1678 V8EXPORT static Local<Object> New(); | |
1679 static inline Object* Cast(Value* obj); | |
1680 | |
1681 private: | |
1682 V8EXPORT Object(); | |
1683 V8EXPORT static void CheckCast(Value* obj); | |
1684 V8EXPORT Local<Value> CheckedGetInternalField(int index); | |
1685 V8EXPORT void* SlowGetPointerFromInternalField(int index); | |
1686 | |
1687 /** | |
1688 * If quick access to the internal field is possible this method | |
1689 * returns the value. Otherwise an empty handle is returned. | |
1690 */ | |
1691 inline Local<Value> UncheckedGetInternalField(int index); | |
1692 }; | |
1693 | |
1694 | |
1695 /** | |
1696 * An instance of the built-in array constructor (ECMA-262, 15.4.2). | |
1697 */ | |
1698 class Array : public Object { | |
1699 public: | |
1700 V8EXPORT uint32_t Length() const; | |
1701 | |
1702 /** | |
1703 * Clones an element at index |index|. Returns an empty | |
1704 * handle if cloning fails (for any reason). | |
1705 */ | |
1706 V8EXPORT Local<Object> CloneElementAt(uint32_t index); | |
1707 | |
1708 /** | |
1709 * Creates a JavaScript array with the given length. If the length | |
1710 * is negative the returned array will have length 0. | |
1711 */ | |
1712 V8EXPORT static Local<Array> New(int length = 0); | |
1713 | |
1714 static inline Array* Cast(Value* obj); | |
1715 private: | |
1716 V8EXPORT Array(); | |
1717 V8EXPORT static void CheckCast(Value* obj); | |
1718 }; | |
1719 | |
1720 | |
1721 /** | |
1722 * A JavaScript function object (ECMA-262, 15.3). | |
1723 */ | |
1724 class Function : public Object { | |
1725 public: | |
1726 V8EXPORT Local<Object> NewInstance() const; | |
1727 V8EXPORT Local<Object> NewInstance(int argc, Handle<Value> argv[]) const; | |
1728 V8EXPORT Local<Value> Call(Handle<Object> recv, | |
1729 int argc, | |
1730 Handle<Value> argv[]); | |
1731 V8EXPORT void SetName(Handle<String> name); | |
1732 V8EXPORT Handle<Value> GetName() const; | |
1733 | |
1734 /** | |
1735 * Name inferred from variable or property assignment of this function. | |
1736 * Used to facilitate debugging and profiling of JavaScript code written | |
1737 * in an OO style, where many functions are anonymous but are assigned | |
1738 * to object properties. | |
1739 */ | |
1740 V8EXPORT Handle<Value> GetInferredName() const; | |
1741 | |
1742 /** | |
1743 * Returns zero based line number of function body and | |
1744 * kLineOffsetNotFound if no information available. | |
1745 */ | |
1746 V8EXPORT int GetScriptLineNumber() const; | |
1747 /** | |
1748 * Returns zero based column number of function body and | |
1749 * kLineOffsetNotFound if no information available. | |
1750 */ | |
1751 V8EXPORT int GetScriptColumnNumber() const; | |
1752 V8EXPORT Handle<Value> GetScriptId() const; | |
1753 V8EXPORT ScriptOrigin GetScriptOrigin() const; | |
1754 static inline Function* Cast(Value* obj); | |
1755 V8EXPORT static const int kLineOffsetNotFound; | |
1756 | |
1757 private: | |
1758 V8EXPORT Function(); | |
1759 V8EXPORT static void CheckCast(Value* obj); | |
1760 }; | |
1761 | |
1762 | |
1763 /** | |
1764 * An instance of the built-in Date constructor (ECMA-262, 15.9). | |
1765 */ | |
1766 class Date : public Object { | |
1767 public: | |
1768 V8EXPORT static Local<Value> New(double time); | |
1769 | |
1770 /** | |
1771 * A specialization of Value::NumberValue that is more efficient | |
1772 * because we know the structure of this object. | |
1773 */ | |
1774 V8EXPORT double NumberValue() const; | |
1775 | |
1776 static inline Date* Cast(v8::Value* obj); | |
1777 | |
1778 /** | |
1779 * Notification that the embedder has changed the time zone, | |
1780 * daylight savings time, or other date / time configuration | |
1781 * parameters. V8 keeps a cache of various values used for | |
1782 * date / time computation. This notification will reset | |
1783 * those cached values for the current context so that date / | |
1784 * time configuration changes would be reflected in the Date | |
1785 * object. | |
1786 * | |
1787 * This API should not be called more than needed as it will | |
1788 * negatively impact the performance of date operations. | |
1789 */ | |
1790 V8EXPORT static void DateTimeConfigurationChangeNotification(); | |
1791 | |
1792 private: | |
1793 V8EXPORT static void CheckCast(v8::Value* obj); | |
1794 }; | |
1795 | |
1796 | |
1797 /** | |
1798 * A Number object (ECMA-262, 4.3.21). | |
1799 */ | |
1800 class NumberObject : public Object { | |
1801 public: | |
1802 V8EXPORT static Local<Value> New(double value); | |
1803 | |
1804 /** | |
1805 * Returns the Number held by the object. | |
1806 */ | |
1807 V8EXPORT double NumberValue() const; | |
1808 | |
1809 static inline NumberObject* Cast(v8::Value* obj); | |
1810 | |
1811 private: | |
1812 V8EXPORT static void CheckCast(v8::Value* obj); | |
1813 }; | |
1814 | |
1815 | |
1816 /** | |
1817 * A Boolean object (ECMA-262, 4.3.15). | |
1818 */ | |
1819 class BooleanObject : public Object { | |
1820 public: | |
1821 V8EXPORT static Local<Value> New(bool value); | |
1822 | |
1823 /** | |
1824 * Returns the Boolean held by the object. | |
1825 */ | |
1826 V8EXPORT bool BooleanValue() const; | |
1827 | |
1828 static inline BooleanObject* Cast(v8::Value* obj); | |
1829 | |
1830 private: | |
1831 V8EXPORT static void CheckCast(v8::Value* obj); | |
1832 }; | |
1833 | |
1834 | |
1835 /** | |
1836 * A String object (ECMA-262, 4.3.18). | |
1837 */ | |
1838 class StringObject : public Object { | |
1839 public: | |
1840 V8EXPORT static Local<Value> New(Handle<String> value); | |
1841 | |
1842 /** | |
1843 * Returns the String held by the object. | |
1844 */ | |
1845 V8EXPORT Local<String> StringValue() const; | |
1846 | |
1847 static inline StringObject* Cast(v8::Value* obj); | |
1848 | |
1849 private: | |
1850 V8EXPORT static void CheckCast(v8::Value* obj); | |
1851 }; | |
1852 | |
1853 | |
1854 /** | |
1855 * An instance of the built-in RegExp constructor (ECMA-262, 15.10). | |
1856 */ | |
1857 class RegExp : public Object { | |
1858 public: | |
1859 /** | |
1860 * Regular expression flag bits. They can be or'ed to enable a set | |
1861 * of flags. | |
1862 */ | |
1863 enum Flags { | |
1864 kNone = 0, | |
1865 kGlobal = 1, | |
1866 kIgnoreCase = 2, | |
1867 kMultiline = 4 | |
1868 }; | |
1869 | |
1870 /** | |
1871 * Creates a regular expression from the given pattern string and | |
1872 * the flags bit field. May throw a JavaScript exception as | |
1873 * described in ECMA-262, 15.10.4.1. | |
1874 * | |
1875 * For example, | |
1876 * RegExp::New(v8::String::New("foo"), | |
1877 * static_cast<RegExp::Flags>(kGlobal | kMultiline)) | |
1878 * is equivalent to evaluating "/foo/gm". | |
1879 */ | |
1880 V8EXPORT static Local<RegExp> New(Handle<String> pattern, | |
1881 Flags flags); | |
1882 | |
1883 /** | |
1884 * Returns the value of the source property: a string representing | |
1885 * the regular expression. | |
1886 */ | |
1887 V8EXPORT Local<String> GetSource() const; | |
1888 | |
1889 /** | |
1890 * Returns the flags bit field. | |
1891 */ | |
1892 V8EXPORT Flags GetFlags() const; | |
1893 | |
1894 static inline RegExp* Cast(v8::Value* obj); | |
1895 | |
1896 private: | |
1897 V8EXPORT static void CheckCast(v8::Value* obj); | |
1898 }; | |
1899 | |
1900 | |
1901 /** | |
1902 * A JavaScript value that wraps a C++ void*. This type of value is | |
1903 * mainly used to associate C++ data structures with JavaScript | |
1904 * objects. | |
1905 * | |
1906 * The Wrap function V8 will return the most optimal Value object wrapping the | |
1907 * C++ void*. The type of the value is not guaranteed to be an External object | |
1908 * and no assumptions about its type should be made. To access the wrapped | |
1909 * value Unwrap should be used, all other operations on that object will lead | |
1910 * to unpredictable results. | |
1911 */ | |
1912 class External : public Value { | |
1913 public: | |
1914 V8EXPORT static Local<Value> Wrap(void* data); | |
1915 static inline void* Unwrap(Handle<Value> obj); | |
1916 | |
1917 V8EXPORT static Local<External> New(void* value); | |
1918 static inline External* Cast(Value* obj); | |
1919 V8EXPORT void* Value() const; | |
1920 private: | |
1921 V8EXPORT External(); | |
1922 V8EXPORT static void CheckCast(v8::Value* obj); | |
1923 static inline void* QuickUnwrap(Handle<v8::Value> obj); | |
1924 V8EXPORT static void* FullUnwrap(Handle<v8::Value> obj); | |
1925 }; | |
1926 | |
1927 | |
1928 // --- Templates --- | |
1929 | |
1930 | |
1931 /** | |
1932 * The superclass of object and function templates. | |
1933 */ | |
1934 class V8EXPORT Template : public Data { | |
1935 public: | |
1936 /** Adds a property to each instance created by this template.*/ | |
1937 void Set(Handle<String> name, Handle<Data> value, | |
1938 PropertyAttribute attributes = None); | |
1939 inline void Set(const char* name, Handle<Data> value); | |
1940 private: | |
1941 Template(); | |
1942 | |
1943 friend class ObjectTemplate; | |
1944 friend class FunctionTemplate; | |
1945 }; | |
1946 | |
1947 | |
1948 /** | |
1949 * The argument information given to function call callbacks. This | |
1950 * class provides access to information about the context of the call, | |
1951 * including the receiver, the number and values of arguments, and | |
1952 * the holder of the function. | |
1953 */ | |
1954 class Arguments { | |
1955 public: | |
1956 inline int Length() const; | |
1957 inline Local<Value> operator[](int i) const; | |
1958 inline Local<Function> Callee() const; | |
1959 inline Local<Object> This() const; | |
1960 inline Local<Object> Holder() const; | |
1961 inline bool IsConstructCall() const; | |
1962 inline Local<Value> Data() const; | |
1963 private: | |
1964 static const int kDataIndex = 0; | |
1965 static const int kCalleeIndex = -1; | |
1966 static const int kHolderIndex = -2; | |
1967 | |
1968 friend class ImplementationUtilities; | |
1969 inline Arguments(internal::Object** implicit_args, | |
1970 internal::Object** values, | |
1971 int length, | |
1972 bool is_construct_call); | |
1973 internal::Object** implicit_args_; | |
1974 internal::Object** values_; | |
1975 int length_; | |
1976 bool is_construct_call_; | |
1977 }; | |
1978 | |
1979 | |
1980 /** | |
1981 * The information passed to an accessor callback about the context | |
1982 * of the property access. | |
1983 */ | |
1984 class V8EXPORT AccessorInfo { | |
1985 public: | |
1986 inline AccessorInfo(internal::Object** args) | |
1987 : args_(args) { } | |
1988 inline Local<Value> Data() const; | |
1989 inline Local<Object> This() const; | |
1990 inline Local<Object> Holder() const; | |
1991 private: | |
1992 internal::Object** args_; | |
1993 }; | |
1994 | |
1995 | |
1996 typedef Handle<Value> (*InvocationCallback)(const Arguments& args); | |
1997 | |
1998 /** | |
1999 * NamedProperty[Getter|Setter] are used as interceptors on object. | |
2000 * See ObjectTemplate::SetNamedPropertyHandler. | |
2001 */ | |
2002 typedef Handle<Value> (*NamedPropertyGetter)(Local<String> property, | |
2003 const AccessorInfo& info); | |
2004 | |
2005 | |
2006 /** | |
2007 * Returns the value if the setter intercepts the request. | |
2008 * Otherwise, returns an empty handle. | |
2009 */ | |
2010 typedef Handle<Value> (*NamedPropertySetter)(Local<String> property, | |
2011 Local<Value> value, | |
2012 const AccessorInfo& info); | |
2013 | |
2014 /** | |
2015 * Returns a non-empty handle if the interceptor intercepts the request. | |
2016 * The result is an integer encoding property attributes (like v8::None, | |
2017 * v8::DontEnum, etc.) | |
2018 */ | |
2019 typedef Handle<Integer> (*NamedPropertyQuery)(Local<String> property, | |
2020 const AccessorInfo& info); | |
2021 | |
2022 | |
2023 /** | |
2024 * Returns a non-empty handle if the deleter intercepts the request. | |
2025 * The return value is true if the property could be deleted and false | |
2026 * otherwise. | |
2027 */ | |
2028 typedef Handle<Boolean> (*NamedPropertyDeleter)(Local<String> property, | |
2029 const AccessorInfo& info); | |
2030 | |
2031 /** | |
2032 * Returns an array containing the names of the properties the named | |
2033 * property getter intercepts. | |
2034 */ | |
2035 typedef Handle<Array> (*NamedPropertyEnumerator)(const AccessorInfo& info); | |
2036 | |
2037 | |
2038 /** | |
2039 * Returns the value of the property if the getter intercepts the | |
2040 * request. Otherwise, returns an empty handle. | |
2041 */ | |
2042 typedef Handle<Value> (*IndexedPropertyGetter)(uint32_t index, | |
2043 const AccessorInfo& info); | |
2044 | |
2045 | |
2046 /** | |
2047 * Returns the value if the setter intercepts the request. | |
2048 * Otherwise, returns an empty handle. | |
2049 */ | |
2050 typedef Handle<Value> (*IndexedPropertySetter)(uint32_t index, | |
2051 Local<Value> value, | |
2052 const AccessorInfo& info); | |
2053 | |
2054 | |
2055 /** | |
2056 * Returns a non-empty handle if the interceptor intercepts the request. | |
2057 * The result is an integer encoding property attributes. | |
2058 */ | |
2059 typedef Handle<Integer> (*IndexedPropertyQuery)(uint32_t index, | |
2060 const AccessorInfo& info); | |
2061 | |
2062 /** | |
2063 * Returns a non-empty handle if the deleter intercepts the request. | |
2064 * The return value is true if the property could be deleted and false | |
2065 * otherwise. | |
2066 */ | |
2067 typedef Handle<Boolean> (*IndexedPropertyDeleter)(uint32_t index, | |
2068 const AccessorInfo& info); | |
2069 | |
2070 /** | |
2071 * Returns an array containing the indices of the properties the | |
2072 * indexed property getter intercepts. | |
2073 */ | |
2074 typedef Handle<Array> (*IndexedPropertyEnumerator)(const AccessorInfo& info); | |
2075 | |
2076 | |
2077 /** | |
2078 * Access type specification. | |
2079 */ | |
2080 enum AccessType { | |
2081 ACCESS_GET, | |
2082 ACCESS_SET, | |
2083 ACCESS_HAS, | |
2084 ACCESS_DELETE, | |
2085 ACCESS_KEYS | |
2086 }; | |
2087 | |
2088 | |
2089 /** | |
2090 * Returns true if cross-context access should be allowed to the named | |
2091 * property with the given key on the host object. | |
2092 */ | |
2093 typedef bool (*NamedSecurityCallback)(Local<Object> host, | |
2094 Local<Value> key, | |
2095 AccessType type, | |
2096 Local<Value> data); | |
2097 | |
2098 | |
2099 /** | |
2100 * Returns true if cross-context access should be allowed to the indexed | |
2101 * property with the given index on the host object. | |
2102 */ | |
2103 typedef bool (*IndexedSecurityCallback)(Local<Object> host, | |
2104 uint32_t index, | |
2105 AccessType type, | |
2106 Local<Value> data); | |
2107 | |
2108 | |
2109 /** | |
2110 * A FunctionTemplate is used to create functions at runtime. There | |
2111 * can only be one function created from a FunctionTemplate in a | |
2112 * context. The lifetime of the created function is equal to the | |
2113 * lifetime of the context. So in case the embedder needs to create | |
2114 * temporary functions that can be collected using Scripts is | |
2115 * preferred. | |
2116 * | |
2117 * A FunctionTemplate can have properties, these properties are added to the | |
2118 * function object when it is created. | |
2119 * | |
2120 * A FunctionTemplate has a corresponding instance template which is | |
2121 * used to create object instances when the function is used as a | |
2122 * constructor. Properties added to the instance template are added to | |
2123 * each object instance. | |
2124 * | |
2125 * A FunctionTemplate can have a prototype template. The prototype template | |
2126 * is used to create the prototype object of the function. | |
2127 * | |
2128 * The following example shows how to use a FunctionTemplate: | |
2129 * | |
2130 * \code | |
2131 * v8::Local<v8::FunctionTemplate> t = v8::FunctionTemplate::New(); | |
2132 * t->Set("func_property", v8::Number::New(1)); | |
2133 * | |
2134 * v8::Local<v8::Template> proto_t = t->PrototypeTemplate(); | |
2135 * proto_t->Set("proto_method", v8::FunctionTemplate::New(InvokeCallback)); | |
2136 * proto_t->Set("proto_const", v8::Number::New(2)); | |
2137 * | |
2138 * v8::Local<v8::ObjectTemplate> instance_t = t->InstanceTemplate(); | |
2139 * instance_t->SetAccessor("instance_accessor", InstanceAccessorCallback); | |
2140 * instance_t->SetNamedPropertyHandler(PropertyHandlerCallback, ...); | |
2141 * instance_t->Set("instance_property", Number::New(3)); | |
2142 * | |
2143 * v8::Local<v8::Function> function = t->GetFunction(); | |
2144 * v8::Local<v8::Object> instance = function->NewInstance(); | |
2145 * \endcode | |
2146 * | |
2147 * Let's use "function" as the JS variable name of the function object | |
2148 * and "instance" for the instance object created above. The function | |
2149 * and the instance will have the following properties: | |
2150 * | |
2151 * \code | |
2152 * func_property in function == true; | |
2153 * function.func_property == 1; | |
2154 * | |
2155 * function.prototype.proto_method() invokes 'InvokeCallback' | |
2156 * function.prototype.proto_const == 2; | |
2157 * | |
2158 * instance instanceof function == true; | |
2159 * instance.instance_accessor calls 'InstanceAccessorCallback' | |
2160 * instance.instance_property == 3; | |
2161 * \endcode | |
2162 * | |
2163 * A FunctionTemplate can inherit from another one by calling the | |
2164 * FunctionTemplate::Inherit method. The following graph illustrates | |
2165 * the semantics of inheritance: | |
2166 * | |
2167 * \code | |
2168 * FunctionTemplate Parent -> Parent() . prototype -> { } | |
2169 * ^ ^ | |
2170 * | Inherit(Parent) | .__proto__ | |
2171 * | | | |
2172 * FunctionTemplate Child -> Child() . prototype -> { } | |
2173 * \endcode | |
2174 * | |
2175 * A FunctionTemplate 'Child' inherits from 'Parent', the prototype | |
2176 * object of the Child() function has __proto__ pointing to the | |
2177 * Parent() function's prototype object. An instance of the Child | |
2178 * function has all properties on Parent's instance templates. | |
2179 * | |
2180 * Let Parent be the FunctionTemplate initialized in the previous | |
2181 * section and create a Child FunctionTemplate by: | |
2182 * | |
2183 * \code | |
2184 * Local<FunctionTemplate> parent = t; | |
2185 * Local<FunctionTemplate> child = FunctionTemplate::New(); | |
2186 * child->Inherit(parent); | |
2187 * | |
2188 * Local<Function> child_function = child->GetFunction(); | |
2189 * Local<Object> child_instance = child_function->NewInstance(); | |
2190 * \endcode | |
2191 * | |
2192 * The Child function and Child instance will have the following | |
2193 * properties: | |
2194 * | |
2195 * \code | |
2196 * child_func.prototype.__proto__ == function.prototype; | |
2197 * child_instance.instance_accessor calls 'InstanceAccessorCallback' | |
2198 * child_instance.instance_property == 3; | |
2199 * \endcode | |
2200 */ | |
2201 class V8EXPORT FunctionTemplate : public Template { | |
2202 public: | |
2203 /** Creates a function template.*/ | |
2204 static Local<FunctionTemplate> New( | |
2205 InvocationCallback callback = 0, | |
2206 Handle<Value> data = Handle<Value>(), | |
2207 Handle<Signature> signature = Handle<Signature>()); | |
2208 /** Returns the unique function instance in the current execution context.*/ | |
2209 Local<Function> GetFunction(); | |
2210 | |
2211 /** | |
2212 * Set the call-handler callback for a FunctionTemplate. This | |
2213 * callback is called whenever the function created from this | |
2214 * FunctionTemplate is called. | |
2215 */ | |
2216 void SetCallHandler(InvocationCallback callback, | |
2217 Handle<Value> data = Handle<Value>()); | |
2218 | |
2219 /** Get the InstanceTemplate. */ | |
2220 Local<ObjectTemplate> InstanceTemplate(); | |
2221 | |
2222 /** Causes the function template to inherit from a parent function template.*/ | |
2223 void Inherit(Handle<FunctionTemplate> parent); | |
2224 | |
2225 /** | |
2226 * A PrototypeTemplate is the template used to create the prototype object | |
2227 * of the function created by this template. | |
2228 */ | |
2229 Local<ObjectTemplate> PrototypeTemplate(); | |
2230 | |
2231 | |
2232 /** | |
2233 * Set the class name of the FunctionTemplate. This is used for | |
2234 * printing objects created with the function created from the | |
2235 * FunctionTemplate as its constructor. | |
2236 */ | |
2237 void SetClassName(Handle<String> name); | |
2238 | |
2239 /** | |
2240 * Determines whether the __proto__ accessor ignores instances of | |
2241 * the function template. If instances of the function template are | |
2242 * ignored, __proto__ skips all instances and instead returns the | |
2243 * next object in the prototype chain. | |
2244 * | |
2245 * Call with a value of true to make the __proto__ accessor ignore | |
2246 * instances of the function template. Call with a value of false | |
2247 * to make the __proto__ accessor not ignore instances of the | |
2248 * function template. By default, instances of a function template | |
2249 * are not ignored. | |
2250 */ | |
2251 void SetHiddenPrototype(bool value); | |
2252 | |
2253 /** | |
2254 * Sets the ReadOnly flag in the attributes of the 'prototype' property | |
2255 * of functions created from this FunctionTemplate to true. | |
2256 */ | |
2257 void ReadOnlyPrototype(); | |
2258 | |
2259 /** | |
2260 * Returns true if the given object is an instance of this function | |
2261 * template. | |
2262 */ | |
2263 bool HasInstance(Handle<Value> object); | |
2264 | |
2265 private: | |
2266 FunctionTemplate(); | |
2267 void AddInstancePropertyAccessor(Handle<String> name, | |
2268 AccessorGetter getter, | |
2269 AccessorSetter setter, | |
2270 Handle<Value> data, | |
2271 AccessControl settings, | |
2272 PropertyAttribute attributes); | |
2273 void SetNamedInstancePropertyHandler(NamedPropertyGetter getter, | |
2274 NamedPropertySetter setter, | |
2275 NamedPropertyQuery query, | |
2276 NamedPropertyDeleter remover, | |
2277 NamedPropertyEnumerator enumerator, | |
2278 Handle<Value> data); | |
2279 void SetIndexedInstancePropertyHandler(IndexedPropertyGetter getter, | |
2280 IndexedPropertySetter setter, | |
2281 IndexedPropertyQuery query, | |
2282 IndexedPropertyDeleter remover, | |
2283 IndexedPropertyEnumerator enumerator, | |
2284 Handle<Value> data); | |
2285 void SetInstanceCallAsFunctionHandler(InvocationCallback callback, | |
2286 Handle<Value> data); | |
2287 | |
2288 friend class Context; | |
2289 friend class ObjectTemplate; | |
2290 }; | |
2291 | |
2292 | |
2293 /** | |
2294 * An ObjectTemplate is used to create objects at runtime. | |
2295 * | |
2296 * Properties added to an ObjectTemplate are added to each object | |
2297 * created from the ObjectTemplate. | |
2298 */ | |
2299 class V8EXPORT ObjectTemplate : public Template { | |
2300 public: | |
2301 /** Creates an ObjectTemplate. */ | |
2302 static Local<ObjectTemplate> New(); | |
2303 | |
2304 /** Creates a new instance of this template.*/ | |
2305 Local<Object> NewInstance(); | |
2306 | |
2307 /** | |
2308 * Sets an accessor on the object template. | |
2309 * | |
2310 * Whenever the property with the given name is accessed on objects | |
2311 * created from this ObjectTemplate the getter and setter callbacks | |
2312 * are called instead of getting and setting the property directly | |
2313 * on the JavaScript object. | |
2314 * | |
2315 * \param name The name of the property for which an accessor is added. | |
2316 * \param getter The callback to invoke when getting the property. | |
2317 * \param setter The callback to invoke when setting the property. | |
2318 * \param data A piece of data that will be passed to the getter and setter | |
2319 * callbacks whenever they are invoked. | |
2320 * \param settings Access control settings for the accessor. This is a bit | |
2321 * field consisting of one of more of | |
2322 * DEFAULT = 0, ALL_CAN_READ = 1, or ALL_CAN_WRITE = 2. | |
2323 * The default is to not allow cross-context access. | |
2324 * ALL_CAN_READ means that all cross-context reads are allowed. | |
2325 * ALL_CAN_WRITE means that all cross-context writes are allowed. | |
2326 * The combination ALL_CAN_READ | ALL_CAN_WRITE can be used to allow all | |
2327 * cross-context access. | |
2328 * \param attribute The attributes of the property for which an accessor | |
2329 * is added. | |
2330 */ | |
2331 void SetAccessor(Handle<String> name, | |
2332 AccessorGetter getter, | |
2333 AccessorSetter setter = 0, | |
2334 Handle<Value> data = Handle<Value>(), | |
2335 AccessControl settings = DEFAULT, | |
2336 PropertyAttribute attribute = None); | |
2337 | |
2338 /** | |
2339 * Sets a named property handler on the object template. | |
2340 * | |
2341 * Whenever a named property is accessed on objects created from | |
2342 * this object template, the provided callback is invoked instead of | |
2343 * accessing the property directly on the JavaScript object. | |
2344 * | |
2345 * \param getter The callback to invoke when getting a property. | |
2346 * \param setter The callback to invoke when setting a property. | |
2347 * \param query The callback to invoke to check if a property is present, | |
2348 * and if present, get its attributes. | |
2349 * \param deleter The callback to invoke when deleting a property. | |
2350 * \param enumerator The callback to invoke to enumerate all the named | |
2351 * properties of an object. | |
2352 * \param data A piece of data that will be passed to the callbacks | |
2353 * whenever they are invoked. | |
2354 */ | |
2355 void SetNamedPropertyHandler(NamedPropertyGetter getter, | |
2356 NamedPropertySetter setter = 0, | |
2357 NamedPropertyQuery query = 0, | |
2358 NamedPropertyDeleter deleter = 0, | |
2359 NamedPropertyEnumerator enumerator = 0, | |
2360 Handle<Value> data = Handle<Value>()); | |
2361 | |
2362 /** | |
2363 * Sets an indexed property handler on the object template. | |
2364 * | |
2365 * Whenever an indexed property is accessed on objects created from | |
2366 * this object template, the provided callback is invoked instead of | |
2367 * accessing the property directly on the JavaScript object. | |
2368 * | |
2369 * \param getter The callback to invoke when getting a property. | |
2370 * \param setter The callback to invoke when setting a property. | |
2371 * \param query The callback to invoke to check if an object has a property. | |
2372 * \param deleter The callback to invoke when deleting a property. | |
2373 * \param enumerator The callback to invoke to enumerate all the indexed | |
2374 * properties of an object. | |
2375 * \param data A piece of data that will be passed to the callbacks | |
2376 * whenever they are invoked. | |
2377 */ | |
2378 void SetIndexedPropertyHandler(IndexedPropertyGetter getter, | |
2379 IndexedPropertySetter setter = 0, | |
2380 IndexedPropertyQuery query = 0, | |
2381 IndexedPropertyDeleter deleter = 0, | |
2382 IndexedPropertyEnumerator enumerator = 0, | |
2383 Handle<Value> data = Handle<Value>()); | |
2384 | |
2385 /** | |
2386 * Sets the callback to be used when calling instances created from | |
2387 * this template as a function. If no callback is set, instances | |
2388 * behave like normal JavaScript objects that cannot be called as a | |
2389 * function. | |
2390 */ | |
2391 void SetCallAsFunctionHandler(InvocationCallback callback, | |
2392 Handle<Value> data = Handle<Value>()); | |
2393 | |
2394 /** | |
2395 * Mark object instances of the template as undetectable. | |
2396 * | |
2397 * In many ways, undetectable objects behave as though they are not | |
2398 * there. They behave like 'undefined' in conditionals and when | |
2399 * printed. However, properties can be accessed and called as on | |
2400 * normal objects. | |
2401 */ | |
2402 void MarkAsUndetectable(); | |
2403 | |
2404 /** | |
2405 * Sets access check callbacks on the object template. | |
2406 * | |
2407 * When accessing properties on instances of this object template, | |
2408 * the access check callback will be called to determine whether or | |
2409 * not to allow cross-context access to the properties. | |
2410 * The last parameter specifies whether access checks are turned | |
2411 * on by default on instances. If access checks are off by default, | |
2412 * they can be turned on on individual instances by calling | |
2413 * Object::TurnOnAccessCheck(). | |
2414 */ | |
2415 void SetAccessCheckCallbacks(NamedSecurityCallback named_handler, | |
2416 IndexedSecurityCallback indexed_handler, | |
2417 Handle<Value> data = Handle<Value>(), | |
2418 bool turned_on_by_default = true); | |
2419 | |
2420 /** | |
2421 * Gets the number of internal fields for objects generated from | |
2422 * this template. | |
2423 */ | |
2424 int InternalFieldCount(); | |
2425 | |
2426 /** | |
2427 * Sets the number of internal fields for objects generated from | |
2428 * this template. | |
2429 */ | |
2430 void SetInternalFieldCount(int value); | |
2431 | |
2432 private: | |
2433 ObjectTemplate(); | |
2434 static Local<ObjectTemplate> New(Handle<FunctionTemplate> constructor); | |
2435 friend class FunctionTemplate; | |
2436 }; | |
2437 | |
2438 | |
2439 /** | |
2440 * A Signature specifies which receivers and arguments a function can | |
2441 * legally be called with. | |
2442 */ | |
2443 class V8EXPORT Signature : public Data { | |
2444 public: | |
2445 static Local<Signature> New(Handle<FunctionTemplate> receiver = | |
2446 Handle<FunctionTemplate>(), | |
2447 int argc = 0, | |
2448 Handle<FunctionTemplate> argv[] = 0); | |
2449 private: | |
2450 Signature(); | |
2451 }; | |
2452 | |
2453 | |
2454 /** | |
2455 * A utility for determining the type of objects based on the template | |
2456 * they were constructed from. | |
2457 */ | |
2458 class V8EXPORT TypeSwitch : public Data { | |
2459 public: | |
2460 static Local<TypeSwitch> New(Handle<FunctionTemplate> type); | |
2461 static Local<TypeSwitch> New(int argc, Handle<FunctionTemplate> types[]); | |
2462 int match(Handle<Value> value); | |
2463 private: | |
2464 TypeSwitch(); | |
2465 }; | |
2466 | |
2467 | |
2468 // --- Extensions --- | |
2469 | |
2470 class V8EXPORT ExternalAsciiStringResourceImpl | |
2471 : public String::ExternalAsciiStringResource { | |
2472 public: | |
2473 ExternalAsciiStringResourceImpl() : data_(0), length_(0) {} | |
2474 ExternalAsciiStringResourceImpl(const char* data, size_t length) | |
2475 : data_(data), length_(length) {} | |
2476 const char* data() const { return data_; } | |
2477 size_t length() const { return length_; } | |
2478 | |
2479 private: | |
2480 const char* data_; | |
2481 size_t length_; | |
2482 }; | |
2483 | |
2484 /** | |
2485 * Ignore | |
2486 */ | |
2487 class V8EXPORT Extension { // NOLINT | |
2488 public: | |
2489 // Note that the strings passed into this constructor must live as long | |
2490 // as the Extension itself. | |
2491 Extension(const char* name, | |
2492 const char* source = 0, | |
2493 int dep_count = 0, | |
2494 const char** deps = 0, | |
2495 int source_length = -1); | |
2496 virtual ~Extension() { } | |
2497 virtual v8::Handle<v8::FunctionTemplate> | |
2498 GetNativeFunction(v8::Handle<v8::String> name) { | |
2499 return v8::Handle<v8::FunctionTemplate>(); | |
2500 } | |
2501 | |
2502 const char* name() const { return name_; } | |
2503 size_t source_length() const { return source_length_; } | |
2504 const String::ExternalAsciiStringResource* source() const { | |
2505 return &source_; } | |
2506 int dependency_count() { return dep_count_; } | |
2507 const char** dependencies() { return deps_; } | |
2508 void set_auto_enable(bool value) { auto_enable_ = value; } | |
2509 bool auto_enable() { return auto_enable_; } | |
2510 | |
2511 private: | |
2512 const char* name_; | |
2513 size_t source_length_; // expected to initialize before source_ | |
2514 ExternalAsciiStringResourceImpl source_; | |
2515 int dep_count_; | |
2516 const char** deps_; | |
2517 bool auto_enable_; | |
2518 | |
2519 // Disallow copying and assigning. | |
2520 Extension(const Extension&); | |
2521 void operator=(const Extension&); | |
2522 }; | |
2523 | |
2524 | |
2525 void V8EXPORT RegisterExtension(Extension* extension); | |
2526 | |
2527 | |
2528 /** | |
2529 * Ignore | |
2530 */ | |
2531 class V8EXPORT DeclareExtension { | |
2532 public: | |
2533 inline DeclareExtension(Extension* extension) { | |
2534 RegisterExtension(extension); | |
2535 } | |
2536 }; | |
2537 | |
2538 | |
2539 // --- Statics --- | |
2540 | |
2541 | |
2542 Handle<Primitive> V8EXPORT Undefined(); | |
2543 Handle<Primitive> V8EXPORT Null(); | |
2544 Handle<Boolean> V8EXPORT True(); | |
2545 Handle<Boolean> V8EXPORT False(); | |
2546 | |
2547 | |
2548 /** | |
2549 * A set of constraints that specifies the limits of the runtime's memory use. | |
2550 * You must set the heap size before initializing the VM - the size cannot be | |
2551 * adjusted after the VM is initialized. | |
2552 * | |
2553 * If you are using threads then you should hold the V8::Locker lock while | |
2554 * setting the stack limit and you must set a non-default stack limit separately | |
2555 * for each thread. | |
2556 */ | |
2557 class V8EXPORT ResourceConstraints { | |
2558 public: | |
2559 ResourceConstraints(); | |
2560 int max_young_space_size() const { return max_young_space_size_; } | |
2561 void set_max_young_space_size(int value) { max_young_space_size_ = value; } | |
2562 int max_old_space_size() const { return max_old_space_size_; } | |
2563 void set_max_old_space_size(int value) { max_old_space_size_ = value; } | |
2564 int max_executable_size() { return max_executable_size_; } | |
2565 void set_max_executable_size(int value) { max_executable_size_ = value; } | |
2566 uint32_t* stack_limit() const { return stack_limit_; } | |
2567 // Sets an address beyond which the VM's stack may not grow. | |
2568 void set_stack_limit(uint32_t* value) { stack_limit_ = value; } | |
2569 private: | |
2570 int max_young_space_size_; | |
2571 int max_old_space_size_; | |
2572 int max_executable_size_; | |
2573 uint32_t* stack_limit_; | |
2574 }; | |
2575 | |
2576 | |
2577 bool V8EXPORT SetResourceConstraints(ResourceConstraints* constraints); | |
2578 | |
2579 | |
2580 // --- Exceptions --- | |
2581 | |
2582 | |
2583 typedef void (*FatalErrorCallback)(const char* location, const char* message); | |
2584 | |
2585 | |
2586 typedef void (*MessageCallback)(Handle<Message> message, Handle<Value> data); | |
2587 | |
2588 | |
2589 /** | |
2590 * Schedules an exception to be thrown when returning to JavaScript. When an | |
2591 * exception has been scheduled it is illegal to invoke any JavaScript | |
2592 * operation; the caller must return immediately and only after the exception | |
2593 * has been handled does it become legal to invoke JavaScript operations. | |
2594 */ | |
2595 Handle<Value> V8EXPORT ThrowException(Handle<Value> exception); | |
2596 | |
2597 /** | |
2598 * Create new error objects by calling the corresponding error object | |
2599 * constructor with the message. | |
2600 */ | |
2601 class V8EXPORT Exception { | |
2602 public: | |
2603 static Local<Value> RangeError(Handle<String> message); | |
2604 static Local<Value> ReferenceError(Handle<String> message); | |
2605 static Local<Value> SyntaxError(Handle<String> message); | |
2606 static Local<Value> TypeError(Handle<String> message); | |
2607 static Local<Value> Error(Handle<String> message); | |
2608 }; | |
2609 | |
2610 | |
2611 // --- Counters Callbacks --- | |
2612 | |
2613 typedef int* (*CounterLookupCallback)(const char* name); | |
2614 | |
2615 typedef void* (*CreateHistogramCallback)(const char* name, | |
2616 int min, | |
2617 int max, | |
2618 size_t buckets); | |
2619 | |
2620 typedef void (*AddHistogramSampleCallback)(void* histogram, int sample); | |
2621 | |
2622 // --- Memory Allocation Callback --- | |
2623 enum ObjectSpace { | |
2624 kObjectSpaceNewSpace = 1 << 0, | |
2625 kObjectSpaceOldPointerSpace = 1 << 1, | |
2626 kObjectSpaceOldDataSpace = 1 << 2, | |
2627 kObjectSpaceCodeSpace = 1 << 3, | |
2628 kObjectSpaceMapSpace = 1 << 4, | |
2629 kObjectSpaceLoSpace = 1 << 5, | |
2630 | |
2631 kObjectSpaceAll = kObjectSpaceNewSpace | kObjectSpaceOldPointerSpace | | |
2632 kObjectSpaceOldDataSpace | kObjectSpaceCodeSpace | kObjectSpaceMapSpace | | |
2633 kObjectSpaceLoSpace | |
2634 }; | |
2635 | |
2636 enum AllocationAction { | |
2637 kAllocationActionAllocate = 1 << 0, | |
2638 kAllocationActionFree = 1 << 1, | |
2639 kAllocationActionAll = kAllocationActionAllocate | kAllocationActionFree | |
2640 }; | |
2641 | |
2642 typedef void (*MemoryAllocationCallback)(ObjectSpace space, | |
2643 AllocationAction action, | |
2644 int size); | |
2645 | |
2646 // --- Leave Script Callback --- | |
2647 typedef void (*CallCompletedCallback)(); | |
2648 | |
2649 // --- Failed Access Check Callback --- | |
2650 typedef void (*FailedAccessCheckCallback)(Local<Object> target, | |
2651 AccessType type, | |
2652 Local<Value> data); | |
2653 | |
2654 // --- AllowCodeGenerationFromStrings callbacks --- | |
2655 | |
2656 /** | |
2657 * Callback to check if code generation from strings is allowed. See | |
2658 * Context::AllowCodeGenerationFromStrings. | |
2659 */ | |
2660 typedef bool (*AllowCodeGenerationFromStringsCallback)(Local<Context> context); | |
2661 | |
2662 // --- Garbage Collection Callbacks --- | |
2663 | |
2664 /** | |
2665 * Applications can register callback functions which will be called | |
2666 * before and after a garbage collection. Allocations are not | |
2667 * allowed in the callback functions, you therefore cannot manipulate | |
2668 * objects (set or delete properties for example) since it is possible | |
2669 * such operations will result in the allocation of objects. | |
2670 */ | |
2671 enum GCType { | |
2672 kGCTypeScavenge = 1 << 0, | |
2673 kGCTypeMarkSweepCompact = 1 << 1, | |
2674 kGCTypeAll = kGCTypeScavenge | kGCTypeMarkSweepCompact | |
2675 }; | |
2676 | |
2677 enum GCCallbackFlags { | |
2678 kNoGCCallbackFlags = 0, | |
2679 kGCCallbackFlagCompacted = 1 << 0 | |
2680 }; | |
2681 | |
2682 typedef void (*GCPrologueCallback)(GCType type, GCCallbackFlags flags); | |
2683 typedef void (*GCEpilogueCallback)(GCType type, GCCallbackFlags flags); | |
2684 | |
2685 typedef void (*GCCallback)(); | |
2686 | |
2687 | |
2688 /** | |
2689 * Collection of V8 heap information. | |
2690 * | |
2691 * Instances of this class can be passed to v8::V8::HeapStatistics to | |
2692 * get heap statistics from V8. | |
2693 */ | |
2694 class V8EXPORT HeapStatistics { | |
2695 public: | |
2696 HeapStatistics(); | |
2697 size_t total_heap_size() { return total_heap_size_; } | |
2698 size_t total_heap_size_executable() { return total_heap_size_executable_; } | |
2699 size_t used_heap_size() { return used_heap_size_; } | |
2700 size_t heap_size_limit() { return heap_size_limit_; } | |
2701 | |
2702 private: | |
2703 void set_total_heap_size(size_t size) { total_heap_size_ = size; } | |
2704 void set_total_heap_size_executable(size_t size) { | |
2705 total_heap_size_executable_ = size; | |
2706 } | |
2707 void set_used_heap_size(size_t size) { used_heap_size_ = size; } | |
2708 void set_heap_size_limit(size_t size) { heap_size_limit_ = size; } | |
2709 | |
2710 size_t total_heap_size_; | |
2711 size_t total_heap_size_executable_; | |
2712 size_t used_heap_size_; | |
2713 size_t heap_size_limit_; | |
2714 | |
2715 friend class V8; | |
2716 }; | |
2717 | |
2718 | |
2719 class RetainedObjectInfo; | |
2720 | |
2721 /** | |
2722 * Isolate represents an isolated instance of the V8 engine. V8 | |
2723 * isolates have completely separate states. Objects from one isolate | |
2724 * must not be used in other isolates. When V8 is initialized a | |
2725 * default isolate is implicitly created and entered. The embedder | |
2726 * can create additional isolates and use them in parallel in multiple | |
2727 * threads. An isolate can be entered by at most one thread at any | |
2728 * given time. The Locker/Unlocker API must be used to synchronize. | |
2729 */ | |
2730 class V8EXPORT Isolate { | |
2731 public: | |
2732 /** | |
2733 * Stack-allocated class which sets the isolate for all operations | |
2734 * executed within a local scope. | |
2735 */ | |
2736 class V8EXPORT Scope { | |
2737 public: | |
2738 explicit Scope(Isolate* isolate) : isolate_(isolate) { | |
2739 isolate->Enter(); | |
2740 } | |
2741 | |
2742 ~Scope() { isolate_->Exit(); } | |
2743 | |
2744 private: | |
2745 Isolate* const isolate_; | |
2746 | |
2747 // Prevent copying of Scope objects. | |
2748 Scope(const Scope&); | |
2749 Scope& operator=(const Scope&); | |
2750 }; | |
2751 | |
2752 /** | |
2753 * Creates a new isolate. Does not change the currently entered | |
2754 * isolate. | |
2755 * | |
2756 * When an isolate is no longer used its resources should be freed | |
2757 * by calling Dispose(). Using the delete operator is not allowed. | |
2758 */ | |
2759 static Isolate* New(); | |
2760 | |
2761 /** | |
2762 * Returns the entered isolate for the current thread or NULL in | |
2763 * case there is no current isolate. | |
2764 */ | |
2765 static Isolate* GetCurrent(); | |
2766 | |
2767 /** | |
2768 * Methods below this point require holding a lock (using Locker) in | |
2769 * a multi-threaded environment. | |
2770 */ | |
2771 | |
2772 /** | |
2773 * Sets this isolate as the entered one for the current thread. | |
2774 * Saves the previously entered one (if any), so that it can be | |
2775 * restored when exiting. Re-entering an isolate is allowed. | |
2776 */ | |
2777 void Enter(); | |
2778 | |
2779 /** | |
2780 * Exits this isolate by restoring the previously entered one in the | |
2781 * current thread. The isolate may still stay the same, if it was | |
2782 * entered more than once. | |
2783 * | |
2784 * Requires: this == Isolate::GetCurrent(). | |
2785 */ | |
2786 void Exit(); | |
2787 | |
2788 /** | |
2789 * Disposes the isolate. The isolate must not be entered by any | |
2790 * thread to be disposable. | |
2791 */ | |
2792 void Dispose(); | |
2793 | |
2794 /** | |
2795 * Associate embedder-specific data with the isolate | |
2796 */ | |
2797 void SetData(void* data); | |
2798 | |
2799 /** | |
2800 * Retrive embedder-specific data from the isolate. | |
2801 * Returns NULL if SetData has never been called. | |
2802 */ | |
2803 void* GetData(); | |
2804 | |
2805 private: | |
2806 Isolate(); | |
2807 Isolate(const Isolate&); | |
2808 ~Isolate(); | |
2809 Isolate& operator=(const Isolate&); | |
2810 void* operator new(size_t size); | |
2811 void operator delete(void*, size_t); | |
2812 }; | |
2813 | |
2814 | |
2815 class StartupData { | |
2816 public: | |
2817 enum CompressionAlgorithm { | |
2818 kUncompressed, | |
2819 kBZip2 | |
2820 }; | |
2821 | |
2822 const char* data; | |
2823 int compressed_size; | |
2824 int raw_size; | |
2825 }; | |
2826 | |
2827 | |
2828 /** | |
2829 * A helper class for driving V8 startup data decompression. It is based on | |
2830 * "CompressedStartupData" API functions from the V8 class. It isn't mandatory | |
2831 * for an embedder to use this class, instead, API functions can be used | |
2832 * directly. | |
2833 * | |
2834 * For an example of the class usage, see the "shell.cc" sample application. | |
2835 */ | |
2836 class V8EXPORT StartupDataDecompressor { // NOLINT | |
2837 public: | |
2838 StartupDataDecompressor(); | |
2839 virtual ~StartupDataDecompressor(); | |
2840 int Decompress(); | |
2841 | |
2842 protected: | |
2843 virtual int DecompressData(char* raw_data, | |
2844 int* raw_data_size, | |
2845 const char* compressed_data, | |
2846 int compressed_data_size) = 0; | |
2847 | |
2848 private: | |
2849 char** raw_data; | |
2850 }; | |
2851 | |
2852 | |
2853 /** | |
2854 * EntropySource is used as a callback function when v8 needs a source | |
2855 * of entropy. | |
2856 */ | |
2857 typedef bool (*EntropySource)(unsigned char* buffer, size_t length); | |
2858 | |
2859 | |
2860 /** | |
2861 * ReturnAddressLocationResolver is used as a callback function when v8 is | |
2862 * resolving the location of a return address on the stack. Profilers that | |
2863 * change the return address on the stack can use this to resolve the stack | |
2864 * location to whereever the profiler stashed the original return address. | |
2865 * When invoked, return_addr_location will point to a location on stack where | |
2866 * a machine return address resides, this function should return either the | |
2867 * same pointer, or a pointer to the profiler's copy of the original return | |
2868 * address. | |
2869 */ | |
2870 typedef uintptr_t (*ReturnAddressLocationResolver)( | |
2871 uintptr_t return_addr_location); | |
2872 | |
2873 | |
2874 /** | |
2875 * Interface for iterating though all external resources in the heap. | |
2876 */ | |
2877 class V8EXPORT ExternalResourceVisitor { // NOLINT | |
2878 public: | |
2879 virtual ~ExternalResourceVisitor() {} | |
2880 virtual void VisitExternalString(Handle<String> string) {} | |
2881 }; | |
2882 | |
2883 | |
2884 /** | |
2885 * Container class for static utility functions. | |
2886 */ | |
2887 class V8EXPORT V8 { | |
2888 public: | |
2889 /** Set the callback to invoke in case of fatal errors. */ | |
2890 static void SetFatalErrorHandler(FatalErrorCallback that); | |
2891 | |
2892 /** | |
2893 * Set the callback to invoke to check if code generation from | |
2894 * strings should be allowed. | |
2895 */ | |
2896 static void SetAllowCodeGenerationFromStringsCallback( | |
2897 AllowCodeGenerationFromStringsCallback that); | |
2898 | |
2899 /** | |
2900 * Ignore out-of-memory exceptions. | |
2901 * | |
2902 * V8 running out of memory is treated as a fatal error by default. | |
2903 * This means that the fatal error handler is called and that V8 is | |
2904 * terminated. | |
2905 * | |
2906 * IgnoreOutOfMemoryException can be used to not treat an | |
2907 * out-of-memory situation as a fatal error. This way, the contexts | |
2908 * that did not cause the out of memory problem might be able to | |
2909 * continue execution. | |
2910 */ | |
2911 static void IgnoreOutOfMemoryException(); | |
2912 | |
2913 /** | |
2914 * Check if V8 is dead and therefore unusable. This is the case after | |
2915 * fatal errors such as out-of-memory situations. | |
2916 */ | |
2917 static bool IsDead(); | |
2918 | |
2919 /** | |
2920 * The following 4 functions are to be used when V8 is built with | |
2921 * the 'compress_startup_data' flag enabled. In this case, the | |
2922 * embedder must decompress startup data prior to initializing V8. | |
2923 * | |
2924 * This is how interaction with V8 should look like: | |
2925 * int compressed_data_count = v8::V8::GetCompressedStartupDataCount(); | |
2926 * v8::StartupData* compressed_data = | |
2927 * new v8::StartupData[compressed_data_count]; | |
2928 * v8::V8::GetCompressedStartupData(compressed_data); | |
2929 * ... decompress data (compressed_data can be updated in-place) ... | |
2930 * v8::V8::SetDecompressedStartupData(compressed_data); | |
2931 * ... now V8 can be initialized | |
2932 * ... make sure the decompressed data stays valid until V8 shutdown | |
2933 * | |
2934 * A helper class StartupDataDecompressor is provided. It implements | |
2935 * the protocol of the interaction described above, and can be used in | |
2936 * most cases instead of calling these API functions directly. | |
2937 */ | |
2938 static StartupData::CompressionAlgorithm GetCompressedStartupDataAlgorithm(); | |
2939 static int GetCompressedStartupDataCount(); | |
2940 static void GetCompressedStartupData(StartupData* compressed_data); | |
2941 static void SetDecompressedStartupData(StartupData* decompressed_data); | |
2942 | |
2943 /** | |
2944 * Adds a message listener. | |
2945 * | |
2946 * The same message listener can be added more than once and in that | |
2947 * case it will be called more than once for each message. | |
2948 */ | |
2949 static bool AddMessageListener(MessageCallback that, | |
2950 Handle<Value> data = Handle<Value>()); | |
2951 | |
2952 /** | |
2953 * Remove all message listeners from the specified callback function. | |
2954 */ | |
2955 static void RemoveMessageListeners(MessageCallback that); | |
2956 | |
2957 /** | |
2958 * Tells V8 to capture current stack trace when uncaught exception occurs | |
2959 * and report it to the message listeners. The option is off by default. | |
2960 */ | |
2961 static void SetCaptureStackTraceForUncaughtExceptions( | |
2962 bool capture, | |
2963 int frame_limit = 10, | |
2964 StackTrace::StackTraceOptions options = StackTrace::kOverview); | |
2965 | |
2966 /** | |
2967 * Sets V8 flags from a string. | |
2968 */ | |
2969 static void SetFlagsFromString(const char* str, int length); | |
2970 | |
2971 /** | |
2972 * Sets V8 flags from the command line. | |
2973 */ | |
2974 static void SetFlagsFromCommandLine(int* argc, | |
2975 char** argv, | |
2976 bool remove_flags); | |
2977 | |
2978 /** Get the version string. */ | |
2979 static const char* GetVersion(); | |
2980 | |
2981 /** | |
2982 * Enables the host application to provide a mechanism for recording | |
2983 * statistics counters. | |
2984 */ | |
2985 static void SetCounterFunction(CounterLookupCallback); | |
2986 | |
2987 /** | |
2988 * Enables the host application to provide a mechanism for recording | |
2989 * histograms. The CreateHistogram function returns a | |
2990 * histogram which will later be passed to the AddHistogramSample | |
2991 * function. | |
2992 */ | |
2993 static void SetCreateHistogramFunction(CreateHistogramCallback); | |
2994 static void SetAddHistogramSampleFunction(AddHistogramSampleCallback); | |
2995 | |
2996 /** | |
2997 * Enables the computation of a sliding window of states. The sliding | |
2998 * window information is recorded in statistics counters. | |
2999 */ | |
3000 static void EnableSlidingStateWindow(); | |
3001 | |
3002 /** Callback function for reporting failed access checks.*/ | |
3003 static void SetFailedAccessCheckCallbackFunction(FailedAccessCheckCallback); | |
3004 | |
3005 /** | |
3006 * Enables the host application to receive a notification before a | |
3007 * garbage collection. Allocations are not allowed in the | |
3008 * callback function, you therefore cannot manipulate objects (set | |
3009 * or delete properties for example) since it is possible such | |
3010 * operations will result in the allocation of objects. It is possible | |
3011 * to specify the GCType filter for your callback. But it is not possible to | |
3012 * register the same callback function two times with different | |
3013 * GCType filters. | |
3014 */ | |
3015 static void AddGCPrologueCallback( | |
3016 GCPrologueCallback callback, GCType gc_type_filter = kGCTypeAll); | |
3017 | |
3018 /** | |
3019 * This function removes callback which was installed by | |
3020 * AddGCPrologueCallback function. | |
3021 */ | |
3022 static void RemoveGCPrologueCallback(GCPrologueCallback callback); | |
3023 | |
3024 /** | |
3025 * The function is deprecated. Please use AddGCPrologueCallback instead. | |
3026 * Enables the host application to receive a notification before a | |
3027 * garbage collection. Allocations are not allowed in the | |
3028 * callback function, you therefore cannot manipulate objects (set | |
3029 * or delete properties for example) since it is possible such | |
3030 * operations will result in the allocation of objects. | |
3031 */ | |
3032 static void SetGlobalGCPrologueCallback(GCCallback); | |
3033 | |
3034 /** | |
3035 * Enables the host application to receive a notification after a | |
3036 * garbage collection. Allocations are not allowed in the | |
3037 * callback function, you therefore cannot manipulate objects (set | |
3038 * or delete properties for example) since it is possible such | |
3039 * operations will result in the allocation of objects. It is possible | |
3040 * to specify the GCType filter for your callback. But it is not possible to | |
3041 * register the same callback function two times with different | |
3042 * GCType filters. | |
3043 */ | |
3044 static void AddGCEpilogueCallback( | |
3045 GCEpilogueCallback callback, GCType gc_type_filter = kGCTypeAll); | |
3046 | |
3047 /** | |
3048 * This function removes callback which was installed by | |
3049 * AddGCEpilogueCallback function. | |
3050 */ | |
3051 static void RemoveGCEpilogueCallback(GCEpilogueCallback callback); | |
3052 | |
3053 /** | |
3054 * The function is deprecated. Please use AddGCEpilogueCallback instead. | |
3055 * Enables the host application to receive a notification after a | |
3056 * major garbage collection. Allocations are not allowed in the | |
3057 * callback function, you therefore cannot manipulate objects (set | |
3058 * or delete properties for example) since it is possible such | |
3059 * operations will result in the allocation of objects. | |
3060 */ | |
3061 static void SetGlobalGCEpilogueCallback(GCCallback); | |
3062 | |
3063 /** | |
3064 * Enables the host application to provide a mechanism to be notified | |
3065 * and perform custom logging when V8 Allocates Executable Memory. | |
3066 */ | |
3067 static void AddMemoryAllocationCallback(MemoryAllocationCallback callback, | |
3068 ObjectSpace space, | |
3069 AllocationAction action); | |
3070 | |
3071 /** | |
3072 * Removes callback that was installed by AddMemoryAllocationCallback. | |
3073 */ | |
3074 static void RemoveMemoryAllocationCallback(MemoryAllocationCallback callback); | |
3075 | |
3076 /** | |
3077 * Adds a callback to notify the host application when a script finished | |
3078 * running. If a script re-enters the runtime during executing, the | |
3079 * CallCompletedCallback is only invoked when the outer-most script | |
3080 * execution ends. Executing scripts inside the callback do not trigger | |
3081 * further callbacks. | |
3082 */ | |
3083 static void AddCallCompletedCallback(CallCompletedCallback callback); | |
3084 | |
3085 /** | |
3086 * Removes callback that was installed by AddCallCompletedCallback. | |
3087 */ | |
3088 static void RemoveCallCompletedCallback(CallCompletedCallback callback); | |
3089 | |
3090 /** | |
3091 * Allows the host application to group objects together. If one | |
3092 * object in the group is alive, all objects in the group are alive. | |
3093 * After each garbage collection, object groups are removed. It is | |
3094 * intended to be used in the before-garbage-collection callback | |
3095 * function, for instance to simulate DOM tree connections among JS | |
3096 * wrapper objects. | |
3097 * See v8-profiler.h for RetainedObjectInfo interface description. | |
3098 */ | |
3099 static void AddObjectGroup(Persistent<Value>* objects, | |
3100 size_t length, | |
3101 RetainedObjectInfo* info = NULL); | |
3102 | |
3103 /** | |
3104 * Allows the host application to declare implicit references between | |
3105 * the objects: if |parent| is alive, all |children| are alive too. | |
3106 * After each garbage collection, all implicit references | |
3107 * are removed. It is intended to be used in the before-garbage-collection | |
3108 * callback function. | |
3109 */ | |
3110 static void AddImplicitReferences(Persistent<Object> parent, | |
3111 Persistent<Value>* children, | |
3112 size_t length); | |
3113 | |
3114 /** | |
3115 * Initializes from snapshot if possible. Otherwise, attempts to | |
3116 * initialize from scratch. This function is called implicitly if | |
3117 * you use the API without calling it first. | |
3118 */ | |
3119 static bool Initialize(); | |
3120 | |
3121 /** | |
3122 * Allows the host application to provide a callback which can be used | |
3123 * as a source of entropy for random number generators. | |
3124 */ | |
3125 static void SetEntropySource(EntropySource source); | |
3126 | |
3127 /** | |
3128 * Allows the host application to provide a callback that allows v8 to | |
3129 * cooperate with a profiler that rewrites return addresses on stack. | |
3130 */ | |
3131 static void SetReturnAddressLocationResolver( | |
3132 ReturnAddressLocationResolver return_address_resolver); | |
3133 | |
3134 /** | |
3135 * Adjusts the amount of registered external memory. Used to give | |
3136 * V8 an indication of the amount of externally allocated memory | |
3137 * that is kept alive by JavaScript objects. V8 uses this to decide | |
3138 * when to perform global garbage collections. Registering | |
3139 * externally allocated memory will trigger global garbage | |
3140 * collections more often than otherwise in an attempt to garbage | |
3141 * collect the JavaScript objects keeping the externally allocated | |
3142 * memory alive. | |
3143 * | |
3144 * \param change_in_bytes the change in externally allocated memory | |
3145 * that is kept alive by JavaScript objects. | |
3146 * \returns the adjusted value. | |
3147 */ | |
3148 static int AdjustAmountOfExternalAllocatedMemory(int change_in_bytes); | |
3149 | |
3150 /** | |
3151 * Suspends recording of tick samples in the profiler. | |
3152 * When the V8 profiling mode is enabled (usually via command line | |
3153 * switches) this function suspends recording of tick samples. | |
3154 * Profiling ticks are discarded until ResumeProfiler() is called. | |
3155 * | |
3156 * See also the --prof and --prof_auto command line switches to | |
3157 * enable V8 profiling. | |
3158 */ | |
3159 static void PauseProfiler(); | |
3160 | |
3161 /** | |
3162 * Resumes recording of tick samples in the profiler. | |
3163 * See also PauseProfiler(). | |
3164 */ | |
3165 static void ResumeProfiler(); | |
3166 | |
3167 /** | |
3168 * Return whether profiler is currently paused. | |
3169 */ | |
3170 static bool IsProfilerPaused(); | |
3171 | |
3172 /** | |
3173 * Retrieve the V8 thread id of the calling thread. | |
3174 * | |
3175 * The thread id for a thread should only be retrieved after the V8 | |
3176 * lock has been acquired with a Locker object with that thread. | |
3177 */ | |
3178 static int GetCurrentThreadId(); | |
3179 | |
3180 /** | |
3181 * Forcefully terminate execution of a JavaScript thread. This can | |
3182 * be used to terminate long-running scripts. | |
3183 * | |
3184 * TerminateExecution should only be called when then V8 lock has | |
3185 * been acquired with a Locker object. Therefore, in order to be | |
3186 * able to terminate long-running threads, preemption must be | |
3187 * enabled to allow the user of TerminateExecution to acquire the | |
3188 * lock. | |
3189 * | |
3190 * The termination is achieved by throwing an exception that is | |
3191 * uncatchable by JavaScript exception handlers. Termination | |
3192 * exceptions act as if they were caught by a C++ TryCatch exception | |
3193 * handler. If forceful termination is used, any C++ TryCatch | |
3194 * exception handler that catches an exception should check if that | |
3195 * exception is a termination exception and immediately return if | |
3196 * that is the case. Returning immediately in that case will | |
3197 * continue the propagation of the termination exception if needed. | |
3198 * | |
3199 * The thread id passed to TerminateExecution must have been | |
3200 * obtained by calling GetCurrentThreadId on the thread in question. | |
3201 * | |
3202 * \param thread_id The thread id of the thread to terminate. | |
3203 */ | |
3204 static void TerminateExecution(int thread_id); | |
3205 | |
3206 /** | |
3207 * Forcefully terminate the current thread of JavaScript execution | |
3208 * in the given isolate. If no isolate is provided, the default | |
3209 * isolate is used. | |
3210 * | |
3211 * This method can be used by any thread even if that thread has not | |
3212 * acquired the V8 lock with a Locker object. | |
3213 * | |
3214 * \param isolate The isolate in which to terminate the current JS execution. | |
3215 */ | |
3216 static void TerminateExecution(Isolate* isolate = NULL); | |
3217 | |
3218 /** | |
3219 * Is V8 terminating JavaScript execution. | |
3220 * | |
3221 * Returns true if JavaScript execution is currently terminating | |
3222 * because of a call to TerminateExecution. In that case there are | |
3223 * still JavaScript frames on the stack and the termination | |
3224 * exception is still active. | |
3225 * | |
3226 * \param isolate The isolate in which to check. | |
3227 */ | |
3228 static bool IsExecutionTerminating(Isolate* isolate = NULL); | |
3229 | |
3230 /** | |
3231 * Releases any resources used by v8 and stops any utility threads | |
3232 * that may be running. Note that disposing v8 is permanent, it | |
3233 * cannot be reinitialized. | |
3234 * | |
3235 * It should generally not be necessary to dispose v8 before exiting | |
3236 * a process, this should happen automatically. It is only necessary | |
3237 * to use if the process needs the resources taken up by v8. | |
3238 */ | |
3239 static bool Dispose(); | |
3240 | |
3241 /** | |
3242 * Get statistics about the heap memory usage. | |
3243 */ | |
3244 static void GetHeapStatistics(HeapStatistics* heap_statistics); | |
3245 | |
3246 /** | |
3247 * Iterates through all external resources referenced from current isolate | |
3248 * heap. This method is not expected to be used except for debugging purposes | |
3249 * and may be quite slow. | |
3250 */ | |
3251 static void VisitExternalResources(ExternalResourceVisitor* visitor); | |
3252 | |
3253 /** | |
3254 * Optional notification that the embedder is idle. | |
3255 * V8 uses the notification to reduce memory footprint. | |
3256 * This call can be used repeatedly if the embedder remains idle. | |
3257 * Returns true if the embedder should stop calling IdleNotification | |
3258 * until real work has been done. This indicates that V8 has done | |
3259 * as much cleanup as it will be able to do. | |
3260 * | |
3261 * The hint argument specifies the amount of work to be done in the function | |
3262 * on scale from 1 to 1000. There is no guarantee that the actual work will | |
3263 * match the hint. | |
3264 */ | |
3265 static bool IdleNotification(int hint = 1000); | |
3266 | |
3267 /** | |
3268 * Optional notification that the system is running low on memory. | |
3269 * V8 uses these notifications to attempt to free memory. | |
3270 */ | |
3271 static void LowMemoryNotification(); | |
3272 | |
3273 /** | |
3274 * Optional notification that a context has been disposed. V8 uses | |
3275 * these notifications to guide the GC heuristic. Returns the number | |
3276 * of context disposals - including this one - since the last time | |
3277 * V8 had a chance to clean up. | |
3278 */ | |
3279 static int ContextDisposedNotification(); | |
3280 | |
3281 private: | |
3282 V8(); | |
3283 | |
3284 static internal::Object** GlobalizeReference(internal::Object** handle); | |
3285 static void DisposeGlobal(internal::Object** global_handle); | |
3286 static void MakeWeak(internal::Object** global_handle, | |
3287 void* data, | |
3288 WeakReferenceCallback); | |
3289 static void ClearWeak(internal::Object** global_handle); | |
3290 static void MarkIndependent(internal::Object** global_handle); | |
3291 static bool IsGlobalNearDeath(internal::Object** global_handle); | |
3292 static bool IsGlobalWeak(internal::Object** global_handle); | |
3293 static void SetWrapperClassId(internal::Object** global_handle, | |
3294 uint16_t class_id); | |
3295 | |
3296 template <class T> friend class Handle; | |
3297 template <class T> friend class Local; | |
3298 template <class T> friend class Persistent; | |
3299 friend class Context; | |
3300 }; | |
3301 | |
3302 | |
3303 /** | |
3304 * An external exception handler. | |
3305 */ | |
3306 class V8EXPORT TryCatch { | |
3307 public: | |
3308 /** | |
3309 * Creates a new try/catch block and registers it with v8. | |
3310 */ | |
3311 TryCatch(); | |
3312 | |
3313 /** | |
3314 * Unregisters and deletes this try/catch block. | |
3315 */ | |
3316 ~TryCatch(); | |
3317 | |
3318 /** | |
3319 * Returns true if an exception has been caught by this try/catch block. | |
3320 */ | |
3321 bool HasCaught() const; | |
3322 | |
3323 /** | |
3324 * For certain types of exceptions, it makes no sense to continue | |
3325 * execution. | |
3326 * | |
3327 * Currently, the only type of exception that can be caught by a | |
3328 * TryCatch handler and for which it does not make sense to continue | |
3329 * is termination exception. Such exceptions are thrown when the | |
3330 * TerminateExecution methods are called to terminate a long-running | |
3331 * script. | |
3332 * | |
3333 * If CanContinue returns false, the correct action is to perform | |
3334 * any C++ cleanup needed and then return. | |
3335 */ | |
3336 bool CanContinue() const; | |
3337 | |
3338 /** | |
3339 * Throws the exception caught by this TryCatch in a way that avoids | |
3340 * it being caught again by this same TryCatch. As with ThrowException | |
3341 * it is illegal to execute any JavaScript operations after calling | |
3342 * ReThrow; the caller must return immediately to where the exception | |
3343 * is caught. | |
3344 */ | |
3345 Handle<Value> ReThrow(); | |
3346 | |
3347 /** | |
3348 * Returns the exception caught by this try/catch block. If no exception has | |
3349 * been caught an empty handle is returned. | |
3350 * | |
3351 * The returned handle is valid until this TryCatch block has been destroyed. | |
3352 */ | |
3353 Local<Value> Exception() const; | |
3354 | |
3355 /** | |
3356 * Returns the .stack property of the thrown object. If no .stack | |
3357 * property is present an empty handle is returned. | |
3358 */ | |
3359 Local<Value> StackTrace() const; | |
3360 | |
3361 /** | |
3362 * Returns the message associated with this exception. If there is | |
3363 * no message associated an empty handle is returned. | |
3364 * | |
3365 * The returned handle is valid until this TryCatch block has been | |
3366 * destroyed. | |
3367 */ | |
3368 Local<v8::Message> Message() const; | |
3369 | |
3370 /** | |
3371 * Clears any exceptions that may have been caught by this try/catch block. | |
3372 * After this method has been called, HasCaught() will return false. | |
3373 * | |
3374 * It is not necessary to clear a try/catch block before using it again; if | |
3375 * another exception is thrown the previously caught exception will just be | |
3376 * overwritten. However, it is often a good idea since it makes it easier | |
3377 * to determine which operation threw a given exception. | |
3378 */ | |
3379 void Reset(); | |
3380 | |
3381 /** | |
3382 * Set verbosity of the external exception handler. | |
3383 * | |
3384 * By default, exceptions that are caught by an external exception | |
3385 * handler are not reported. Call SetVerbose with true on an | |
3386 * external exception handler to have exceptions caught by the | |
3387 * handler reported as if they were not caught. | |
3388 */ | |
3389 void SetVerbose(bool value); | |
3390 | |
3391 /** | |
3392 * Set whether or not this TryCatch should capture a Message object | |
3393 * which holds source information about where the exception | |
3394 * occurred. True by default. | |
3395 */ | |
3396 void SetCaptureMessage(bool value); | |
3397 | |
3398 private: | |
3399 v8::internal::Isolate* isolate_; | |
3400 void* next_; | |
3401 void* exception_; | |
3402 void* message_; | |
3403 bool is_verbose_ : 1; | |
3404 bool can_continue_ : 1; | |
3405 bool capture_message_ : 1; | |
3406 bool rethrow_ : 1; | |
3407 | |
3408 friend class v8::internal::Isolate; | |
3409 }; | |
3410 | |
3411 | |
3412 // --- Context --- | |
3413 | |
3414 | |
3415 /** | |
3416 * Ignore | |
3417 */ | |
3418 class V8EXPORT ExtensionConfiguration { | |
3419 public: | |
3420 ExtensionConfiguration(int name_count, const char* names[]) | |
3421 : name_count_(name_count), names_(names) { } | |
3422 private: | |
3423 friend class ImplementationUtilities; | |
3424 int name_count_; | |
3425 const char** names_; | |
3426 }; | |
3427 | |
3428 | |
3429 /** | |
3430 * A sandboxed execution context with its own set of built-in objects | |
3431 * and functions. | |
3432 */ | |
3433 class V8EXPORT Context { | |
3434 public: | |
3435 /** | |
3436 * Returns the global proxy object or global object itself for | |
3437 * detached contexts. | |
3438 * | |
3439 * Global proxy object is a thin wrapper whose prototype points to | |
3440 * actual context's global object with the properties like Object, etc. | |
3441 * This is done that way for security reasons (for more details see | |
3442 * https://wiki.mozilla.org/Gecko:SplitWindow). | |
3443 * | |
3444 * Please note that changes to global proxy object prototype most probably | |
3445 * would break VM---v8 expects only global object as a prototype of | |
3446 * global proxy object. | |
3447 * | |
3448 * If DetachGlobal() has been invoked, Global() would return actual global | |
3449 * object until global is reattached with ReattachGlobal(). | |
3450 */ | |
3451 Local<Object> Global(); | |
3452 | |
3453 /** | |
3454 * Detaches the global object from its context before | |
3455 * the global object can be reused to create a new context. | |
3456 */ | |
3457 void DetachGlobal(); | |
3458 | |
3459 /** | |
3460 * Reattaches a global object to a context. This can be used to | |
3461 * restore the connection between a global object and a context | |
3462 * after DetachGlobal has been called. | |
3463 * | |
3464 * \param global_object The global object to reattach to the | |
3465 * context. For this to work, the global object must be the global | |
3466 * object that was associated with this context before a call to | |
3467 * DetachGlobal. | |
3468 */ | |
3469 void ReattachGlobal(Handle<Object> global_object); | |
3470 | |
3471 /** Creates a new context. | |
3472 * | |
3473 * Returns a persistent handle to the newly allocated context. This | |
3474 * persistent handle has to be disposed when the context is no | |
3475 * longer used so the context can be garbage collected. | |
3476 * | |
3477 * \param extensions An optional extension configuration containing | |
3478 * the extensions to be installed in the newly created context. | |
3479 * | |
3480 * \param global_template An optional object template from which the | |
3481 * global object for the newly created context will be created. | |
3482 * | |
3483 * \param global_object An optional global object to be reused for | |
3484 * the newly created context. This global object must have been | |
3485 * created by a previous call to Context::New with the same global | |
3486 * template. The state of the global object will be completely reset | |
3487 * and only object identify will remain. | |
3488 */ | |
3489 static Persistent<Context> New( | |
3490 ExtensionConfiguration* extensions = NULL, | |
3491 Handle<ObjectTemplate> global_template = Handle<ObjectTemplate>(), | |
3492 Handle<Value> global_object = Handle<Value>()); | |
3493 | |
3494 /** Returns the last entered context. */ | |
3495 static Local<Context> GetEntered(); | |
3496 | |
3497 /** Returns the context that is on the top of the stack. */ | |
3498 static Local<Context> GetCurrent(); | |
3499 | |
3500 /** | |
3501 * Returns the context of the calling JavaScript code. That is the | |
3502 * context of the top-most JavaScript frame. If there are no | |
3503 * JavaScript frames an empty handle is returned. | |
3504 */ | |
3505 static Local<Context> GetCalling(); | |
3506 | |
3507 /** | |
3508 * Sets the security token for the context. To access an object in | |
3509 * another context, the security tokens must match. | |
3510 */ | |
3511 void SetSecurityToken(Handle<Value> token); | |
3512 | |
3513 /** Restores the security token to the default value. */ | |
3514 void UseDefaultSecurityToken(); | |
3515 | |
3516 /** Returns the security token of this context.*/ | |
3517 Handle<Value> GetSecurityToken(); | |
3518 | |
3519 /** | |
3520 * Enter this context. After entering a context, all code compiled | |
3521 * and run is compiled and run in this context. If another context | |
3522 * is already entered, this old context is saved so it can be | |
3523 * restored when the new context is exited. | |
3524 */ | |
3525 void Enter(); | |
3526 | |
3527 /** | |
3528 * Exit this context. Exiting the current context restores the | |
3529 * context that was in place when entering the current context. | |
3530 */ | |
3531 void Exit(); | |
3532 | |
3533 /** Returns true if the context has experienced an out of memory situation. */ | |
3534 bool HasOutOfMemoryException(); | |
3535 | |
3536 /** Returns true if V8 has a current context. */ | |
3537 static bool InContext(); | |
3538 | |
3539 /** | |
3540 * Associate an additional data object with the context. This is mainly used | |
3541 * with the debugger to provide additional information on the context through | |
3542 * the debugger API. | |
3543 */ | |
3544 void SetData(Handle<String> data); | |
3545 Local<Value> GetData(); | |
3546 | |
3547 /** | |
3548 * Control whether code generation from strings is allowed. Calling | |
3549 * this method with false will disable 'eval' and the 'Function' | |
3550 * constructor for code running in this context. If 'eval' or the | |
3551 * 'Function' constructor are used an exception will be thrown. | |
3552 * | |
3553 * If code generation from strings is not allowed the | |
3554 * V8::AllowCodeGenerationFromStrings callback will be invoked if | |
3555 * set before blocking the call to 'eval' or the 'Function' | |
3556 * constructor. If that callback returns true, the call will be | |
3557 * allowed, otherwise an exception will be thrown. If no callback is | |
3558 * set an exception will be thrown. | |
3559 */ | |
3560 void AllowCodeGenerationFromStrings(bool allow); | |
3561 | |
3562 /** | |
3563 * Returns true if code generation from strings is allowed for the context. | |
3564 * For more details see AllowCodeGenerationFromStrings(bool) documentation. | |
3565 */ | |
3566 bool IsCodeGenerationFromStringsAllowed(); | |
3567 | |
3568 /** | |
3569 * Stack-allocated class which sets the execution context for all | |
3570 * operations executed within a local scope. | |
3571 */ | |
3572 class Scope { | |
3573 public: | |
3574 explicit inline Scope(Handle<Context> context) : context_(context) { | |
3575 context_->Enter(); | |
3576 } | |
3577 inline ~Scope() { context_->Exit(); } | |
3578 private: | |
3579 Handle<Context> context_; | |
3580 }; | |
3581 | |
3582 private: | |
3583 friend class Value; | |
3584 friend class Script; | |
3585 friend class Object; | |
3586 friend class Function; | |
3587 }; | |
3588 | |
3589 | |
3590 /** | |
3591 * Multiple threads in V8 are allowed, but only one thread at a time | |
3592 * is allowed to use any given V8 isolate. See Isolate class | |
3593 * comments. The definition of 'using V8 isolate' includes | |
3594 * accessing handles or holding onto object pointers obtained | |
3595 * from V8 handles while in the particular V8 isolate. It is up | |
3596 * to the user of V8 to ensure (perhaps with locking) that this | |
3597 * constraint is not violated. In addition to any other synchronization | |
3598 * mechanism that may be used, the v8::Locker and v8::Unlocker classes | |
3599 * must be used to signal thead switches to V8. | |
3600 * | |
3601 * v8::Locker is a scoped lock object. While it's | |
3602 * active (i.e. between its construction and destruction) the current thread is | |
3603 * allowed to use the locked isolate. V8 guarantees that an isolate can be | |
3604 * locked by at most one thread at any time. In other words, the scope of a | |
3605 * v8::Locker is a critical section. | |
3606 * | |
3607 * Sample usage: | |
3608 * \code | |
3609 * ... | |
3610 * { | |
3611 * v8::Locker locker(isolate); | |
3612 * v8::Isolate::Scope isolate_scope(isolate); | |
3613 * ... | |
3614 * // Code using V8 and isolate goes here. | |
3615 * ... | |
3616 * } // Destructor called here | |
3617 * \endcode | |
3618 * | |
3619 * If you wish to stop using V8 in a thread A you can do this either | |
3620 * by destroying the v8::Locker object as above or by constructing a | |
3621 * v8::Unlocker object: | |
3622 * | |
3623 * \code | |
3624 * { | |
3625 * isolate->Exit(); | |
3626 * v8::Unlocker unlocker(isolate); | |
3627 * ... | |
3628 * // Code not using V8 goes here while V8 can run in another thread. | |
3629 * ... | |
3630 * } // Destructor called here. | |
3631 * isolate->Enter(); | |
3632 * \endcode | |
3633 * | |
3634 * The Unlocker object is intended for use in a long-running callback | |
3635 * from V8, where you want to release the V8 lock for other threads to | |
3636 * use. | |
3637 * | |
3638 * The v8::Locker is a recursive lock. That is, you can lock more than | |
3639 * once in a given thread. This can be useful if you have code that can | |
3640 * be called either from code that holds the lock or from code that does | |
3641 * not. The Unlocker is not recursive so you can not have several | |
3642 * Unlockers on the stack at once, and you can not use an Unlocker in a | |
3643 * thread that is not inside a Locker's scope. | |
3644 * | |
3645 * An unlocker will unlock several lockers if it has to and reinstate | |
3646 * the correct depth of locking on its destruction. eg.: | |
3647 * | |
3648 * \code | |
3649 * // V8 not locked. | |
3650 * { | |
3651 * v8::Locker locker(isolate); | |
3652 * Isolate::Scope isolate_scope(isolate); | |
3653 * // V8 locked. | |
3654 * { | |
3655 * v8::Locker another_locker(isolate); | |
3656 * // V8 still locked (2 levels). | |
3657 * { | |
3658 * isolate->Exit(); | |
3659 * v8::Unlocker unlocker(isolate); | |
3660 * // V8 not locked. | |
3661 * } | |
3662 * isolate->Enter(); | |
3663 * // V8 locked again (2 levels). | |
3664 * } | |
3665 * // V8 still locked (1 level). | |
3666 * } | |
3667 * // V8 Now no longer locked. | |
3668 * \endcode | |
3669 * | |
3670 * | |
3671 */ | |
3672 class V8EXPORT Unlocker { | |
3673 public: | |
3674 /** | |
3675 * Initialize Unlocker for a given Isolate. NULL means default isolate. | |
3676 */ | |
3677 explicit Unlocker(Isolate* isolate = NULL); | |
3678 ~Unlocker(); | |
3679 private: | |
3680 internal::Isolate* isolate_; | |
3681 }; | |
3682 | |
3683 | |
3684 class V8EXPORT Locker { | |
3685 public: | |
3686 /** | |
3687 * Initialize Locker for a given Isolate. NULL means default isolate. | |
3688 */ | |
3689 explicit Locker(Isolate* isolate = NULL); | |
3690 ~Locker(); | |
3691 | |
3692 /** | |
3693 * Start preemption. | |
3694 * | |
3695 * When preemption is started, a timer is fired every n milliseconds | |
3696 * that will switch between multiple threads that are in contention | |
3697 * for the V8 lock. | |
3698 */ | |
3699 static void StartPreemption(int every_n_ms); | |
3700 | |
3701 /** | |
3702 * Stop preemption. | |
3703 */ | |
3704 static void StopPreemption(); | |
3705 | |
3706 /** | |
3707 * Returns whether or not the locker for a given isolate, or default isolate | |
3708 * if NULL is given, is locked by the current thread. | |
3709 */ | |
3710 static bool IsLocked(Isolate* isolate = NULL); | |
3711 | |
3712 /** | |
3713 * Returns whether v8::Locker is being used by this V8 instance. | |
3714 */ | |
3715 static bool IsActive(); | |
3716 | |
3717 private: | |
3718 bool has_lock_; | |
3719 bool top_level_; | |
3720 internal::Isolate* isolate_; | |
3721 | |
3722 static bool active_; | |
3723 | |
3724 // Disallow copying and assigning. | |
3725 Locker(const Locker&); | |
3726 void operator=(const Locker&); | |
3727 }; | |
3728 | |
3729 | |
3730 /** | |
3731 * An interface for exporting data from V8, using "push" model. | |
3732 */ | |
3733 class V8EXPORT OutputStream { // NOLINT | |
3734 public: | |
3735 enum OutputEncoding { | |
3736 kAscii = 0 // 7-bit ASCII. | |
3737 }; | |
3738 enum WriteResult { | |
3739 kContinue = 0, | |
3740 kAbort = 1 | |
3741 }; | |
3742 virtual ~OutputStream() {} | |
3743 /** Notify about the end of stream. */ | |
3744 virtual void EndOfStream() = 0; | |
3745 /** Get preferred output chunk size. Called only once. */ | |
3746 virtual int GetChunkSize() { return 1024; } | |
3747 /** Get preferred output encoding. Called only once. */ | |
3748 virtual OutputEncoding GetOutputEncoding() { return kAscii; } | |
3749 /** | |
3750 * Writes the next chunk of snapshot data into the stream. Writing | |
3751 * can be stopped by returning kAbort as function result. EndOfStream | |
3752 * will not be called in case writing was aborted. | |
3753 */ | |
3754 virtual WriteResult WriteAsciiChunk(char* data, int size) = 0; | |
3755 }; | |
3756 | |
3757 | |
3758 /** | |
3759 * An interface for reporting progress and controlling long-running | |
3760 * activities. | |
3761 */ | |
3762 class V8EXPORT ActivityControl { // NOLINT | |
3763 public: | |
3764 enum ControlOption { | |
3765 kContinue = 0, | |
3766 kAbort = 1 | |
3767 }; | |
3768 virtual ~ActivityControl() {} | |
3769 /** | |
3770 * Notify about current progress. The activity can be stopped by | |
3771 * returning kAbort as the callback result. | |
3772 */ | |
3773 virtual ControlOption ReportProgressValue(int done, int total) = 0; | |
3774 }; | |
3775 | |
3776 | |
3777 // --- Implementation --- | |
3778 | |
3779 | |
3780 namespace internal { | |
3781 | |
3782 const int kApiPointerSize = sizeof(void*); // NOLINT | |
3783 const int kApiIntSize = sizeof(int); // NOLINT | |
3784 | |
3785 // Tag information for HeapObject. | |
3786 const int kHeapObjectTag = 1; | |
3787 const int kHeapObjectTagSize = 2; | |
3788 const intptr_t kHeapObjectTagMask = (1 << kHeapObjectTagSize) - 1; | |
3789 | |
3790 // Tag information for Smi. | |
3791 const int kSmiTag = 0; | |
3792 const int kSmiTagSize = 1; | |
3793 const intptr_t kSmiTagMask = (1 << kSmiTagSize) - 1; | |
3794 | |
3795 template <size_t ptr_size> struct SmiTagging; | |
3796 | |
3797 // Smi constants for 32-bit systems. | |
3798 template <> struct SmiTagging<4> { | |
3799 static const int kSmiShiftSize = 0; | |
3800 static const int kSmiValueSize = 31; | |
3801 static inline int SmiToInt(internal::Object* value) { | |
3802 int shift_bits = kSmiTagSize + kSmiShiftSize; | |
3803 // Throw away top 32 bits and shift down (requires >> to be sign extending). | |
3804 return static_cast<int>(reinterpret_cast<intptr_t>(value)) >> shift_bits; | |
3805 } | |
3806 | |
3807 // For 32-bit systems any 2 bytes aligned pointer can be encoded as smi | |
3808 // with a plain reinterpret_cast. | |
3809 static const uintptr_t kEncodablePointerMask = 0x1; | |
3810 static const int kPointerToSmiShift = 0; | |
3811 }; | |
3812 | |
3813 // Smi constants for 64-bit systems. | |
3814 template <> struct SmiTagging<8> { | |
3815 static const int kSmiShiftSize = 31; | |
3816 static const int kSmiValueSize = 32; | |
3817 static inline int SmiToInt(internal::Object* value) { | |
3818 int shift_bits = kSmiTagSize + kSmiShiftSize; | |
3819 // Shift down and throw away top 32 bits. | |
3820 return static_cast<int>(reinterpret_cast<intptr_t>(value) >> shift_bits); | |
3821 } | |
3822 | |
3823 // To maximize the range of pointers that can be encoded | |
3824 // in the available 32 bits, we require them to be 8 bytes aligned. | |
3825 // This gives 2 ^ (32 + 3) = 32G address space covered. | |
3826 // It might be not enough to cover stack allocated objects on some platforms. | |
3827 static const int kPointerAlignment = 3; | |
3828 | |
3829 static const uintptr_t kEncodablePointerMask = | |
3830 ~(uintptr_t(0xffffffff) << kPointerAlignment); | |
3831 | |
3832 static const int kPointerToSmiShift = | |
3833 kSmiTagSize + kSmiShiftSize - kPointerAlignment; | |
3834 }; | |
3835 | |
3836 typedef SmiTagging<kApiPointerSize> PlatformSmiTagging; | |
3837 const int kSmiShiftSize = PlatformSmiTagging::kSmiShiftSize; | |
3838 const int kSmiValueSize = PlatformSmiTagging::kSmiValueSize; | |
3839 const uintptr_t kEncodablePointerMask = | |
3840 PlatformSmiTagging::kEncodablePointerMask; | |
3841 const int kPointerToSmiShift = PlatformSmiTagging::kPointerToSmiShift; | |
3842 | |
3843 template <size_t ptr_size> struct InternalConstants; | |
3844 | |
3845 // Internal constants for 32-bit systems. | |
3846 template <> struct InternalConstants<4> { | |
3847 static const int kStringResourceOffset = 3 * kApiPointerSize; | |
3848 }; | |
3849 | |
3850 // Internal constants for 64-bit systems. | |
3851 template <> struct InternalConstants<8> { | |
3852 static const int kStringResourceOffset = 3 * kApiPointerSize; | |
3853 }; | |
3854 | |
3855 /** | |
3856 * This class exports constants and functionality from within v8 that | |
3857 * is necessary to implement inline functions in the v8 api. Don't | |
3858 * depend on functions and constants defined here. | |
3859 */ | |
3860 class Internals { | |
3861 public: | |
3862 // These values match non-compiler-dependent values defined within | |
3863 // the implementation of v8. | |
3864 static const int kHeapObjectMapOffset = 0; | |
3865 static const int kMapInstanceTypeOffset = 1 * kApiPointerSize + kApiIntSize; | |
3866 static const int kStringResourceOffset = | |
3867 InternalConstants<kApiPointerSize>::kStringResourceOffset; | |
3868 | |
3869 static const int kForeignAddressOffset = kApiPointerSize; | |
3870 static const int kJSObjectHeaderSize = 3 * kApiPointerSize; | |
3871 static const int kFullStringRepresentationMask = 0x07; | |
3872 static const int kExternalTwoByteRepresentationTag = 0x02; | |
3873 | |
3874 static const int kJSObjectType = 0xaa; | |
3875 static const int kFirstNonstringType = 0x80; | |
3876 static const int kForeignType = 0x85; | |
3877 | |
3878 static inline bool HasHeapObjectTag(internal::Object* value) { | |
3879 return ((reinterpret_cast<intptr_t>(value) & kHeapObjectTagMask) == | |
3880 kHeapObjectTag); | |
3881 } | |
3882 | |
3883 static inline bool HasSmiTag(internal::Object* value) { | |
3884 return ((reinterpret_cast<intptr_t>(value) & kSmiTagMask) == kSmiTag); | |
3885 } | |
3886 | |
3887 static inline int SmiValue(internal::Object* value) { | |
3888 return PlatformSmiTagging::SmiToInt(value); | |
3889 } | |
3890 | |
3891 static inline int GetInstanceType(internal::Object* obj) { | |
3892 typedef internal::Object O; | |
3893 O* map = ReadField<O*>(obj, kHeapObjectMapOffset); | |
3894 return ReadField<uint8_t>(map, kMapInstanceTypeOffset); | |
3895 } | |
3896 | |
3897 static inline void* GetExternalPointerFromSmi(internal::Object* value) { | |
3898 const uintptr_t address = reinterpret_cast<uintptr_t>(value); | |
3899 return reinterpret_cast<void*>(address >> kPointerToSmiShift); | |
3900 } | |
3901 | |
3902 static inline void* GetExternalPointer(internal::Object* obj) { | |
3903 if (HasSmiTag(obj)) { | |
3904 return GetExternalPointerFromSmi(obj); | |
3905 } else if (GetInstanceType(obj) == kForeignType) { | |
3906 return ReadField<void*>(obj, kForeignAddressOffset); | |
3907 } else { | |
3908 return NULL; | |
3909 } | |
3910 } | |
3911 | |
3912 static inline bool IsExternalTwoByteString(int instance_type) { | |
3913 int representation = (instance_type & kFullStringRepresentationMask); | |
3914 return representation == kExternalTwoByteRepresentationTag; | |
3915 } | |
3916 | |
3917 template <typename T> | |
3918 static inline T ReadField(Object* ptr, int offset) { | |
3919 uint8_t* addr = reinterpret_cast<uint8_t*>(ptr) + offset - kHeapObjectTag; | |
3920 return *reinterpret_cast<T*>(addr); | |
3921 } | |
3922 | |
3923 static inline bool CanCastToHeapObject(void* o) { return false; } | |
3924 static inline bool CanCastToHeapObject(Context* o) { return true; } | |
3925 static inline bool CanCastToHeapObject(String* o) { return true; } | |
3926 static inline bool CanCastToHeapObject(Object* o) { return true; } | |
3927 static inline bool CanCastToHeapObject(Message* o) { return true; } | |
3928 static inline bool CanCastToHeapObject(StackTrace* o) { return true; } | |
3929 static inline bool CanCastToHeapObject(StackFrame* o) { return true; } | |
3930 }; | |
3931 | |
3932 } // namespace internal | |
3933 | |
3934 | |
3935 template <class T> | |
3936 Local<T>::Local() : Handle<T>() { } | |
3937 | |
3938 | |
3939 template <class T> | |
3940 Local<T> Local<T>::New(Handle<T> that) { | |
3941 if (that.IsEmpty()) return Local<T>(); | |
3942 T* that_ptr = *that; | |
3943 internal::Object** p = reinterpret_cast<internal::Object**>(that_ptr); | |
3944 if (internal::Internals::CanCastToHeapObject(that_ptr)) { | |
3945 return Local<T>(reinterpret_cast<T*>(HandleScope::CreateHandle( | |
3946 reinterpret_cast<internal::HeapObject*>(*p)))); | |
3947 } | |
3948 return Local<T>(reinterpret_cast<T*>(HandleScope::CreateHandle(*p))); | |
3949 } | |
3950 | |
3951 | |
3952 template <class T> | |
3953 Persistent<T> Persistent<T>::New(Handle<T> that) { | |
3954 if (that.IsEmpty()) return Persistent<T>(); | |
3955 internal::Object** p = reinterpret_cast<internal::Object**>(*that); | |
3956 return Persistent<T>(reinterpret_cast<T*>(V8::GlobalizeReference(p))); | |
3957 } | |
3958 | |
3959 | |
3960 template <class T> | |
3961 bool Persistent<T>::IsNearDeath() const { | |
3962 if (this->IsEmpty()) return false; | |
3963 return V8::IsGlobalNearDeath(reinterpret_cast<internal::Object**>(**this)); | |
3964 } | |
3965 | |
3966 | |
3967 template <class T> | |
3968 bool Persistent<T>::IsWeak() const { | |
3969 if (this->IsEmpty()) return false; | |
3970 return V8::IsGlobalWeak(reinterpret_cast<internal::Object**>(**this)); | |
3971 } | |
3972 | |
3973 | |
3974 template <class T> | |
3975 void Persistent<T>::Dispose() { | |
3976 if (this->IsEmpty()) return; | |
3977 V8::DisposeGlobal(reinterpret_cast<internal::Object**>(**this)); | |
3978 } | |
3979 | |
3980 | |
3981 template <class T> | |
3982 Persistent<T>::Persistent() : Handle<T>() { } | |
3983 | |
3984 template <class T> | |
3985 void Persistent<T>::MakeWeak(void* parameters, WeakReferenceCallback callback) { | |
3986 V8::MakeWeak(reinterpret_cast<internal::Object**>(**this), | |
3987 parameters, | |
3988 callback); | |
3989 } | |
3990 | |
3991 template <class T> | |
3992 void Persistent<T>::ClearWeak() { | |
3993 V8::ClearWeak(reinterpret_cast<internal::Object**>(**this)); | |
3994 } | |
3995 | |
3996 template <class T> | |
3997 void Persistent<T>::MarkIndependent() { | |
3998 V8::MarkIndependent(reinterpret_cast<internal::Object**>(**this)); | |
3999 } | |
4000 | |
4001 template <class T> | |
4002 void Persistent<T>::SetWrapperClassId(uint16_t class_id) { | |
4003 V8::SetWrapperClassId(reinterpret_cast<internal::Object**>(**this), class_id); | |
4004 } | |
4005 | |
4006 Arguments::Arguments(internal::Object** implicit_args, | |
4007 internal::Object** values, int length, | |
4008 bool is_construct_call) | |
4009 : implicit_args_(implicit_args), | |
4010 values_(values), | |
4011 length_(length), | |
4012 is_construct_call_(is_construct_call) { } | |
4013 | |
4014 | |
4015 Local<Value> Arguments::operator[](int i) const { | |
4016 if (i < 0 || length_ <= i) return Local<Value>(*Undefined()); | |
4017 return Local<Value>(reinterpret_cast<Value*>(values_ - i)); | |
4018 } | |
4019 | |
4020 | |
4021 Local<Function> Arguments::Callee() const { | |
4022 return Local<Function>(reinterpret_cast<Function*>( | |
4023 &implicit_args_[kCalleeIndex])); | |
4024 } | |
4025 | |
4026 | |
4027 Local<Object> Arguments::This() const { | |
4028 return Local<Object>(reinterpret_cast<Object*>(values_ + 1)); | |
4029 } | |
4030 | |
4031 | |
4032 Local<Object> Arguments::Holder() const { | |
4033 return Local<Object>(reinterpret_cast<Object*>( | |
4034 &implicit_args_[kHolderIndex])); | |
4035 } | |
4036 | |
4037 | |
4038 Local<Value> Arguments::Data() const { | |
4039 return Local<Value>(reinterpret_cast<Value*>(&implicit_args_[kDataIndex])); | |
4040 } | |
4041 | |
4042 | |
4043 bool Arguments::IsConstructCall() const { | |
4044 return is_construct_call_; | |
4045 } | |
4046 | |
4047 | |
4048 int Arguments::Length() const { | |
4049 return length_; | |
4050 } | |
4051 | |
4052 | |
4053 template <class T> | |
4054 Local<T> HandleScope::Close(Handle<T> value) { | |
4055 internal::Object** before = reinterpret_cast<internal::Object**>(*value); | |
4056 internal::Object** after = RawClose(before); | |
4057 return Local<T>(reinterpret_cast<T*>(after)); | |
4058 } | |
4059 | |
4060 Handle<Value> ScriptOrigin::ResourceName() const { | |
4061 return resource_name_; | |
4062 } | |
4063 | |
4064 | |
4065 Handle<Integer> ScriptOrigin::ResourceLineOffset() const { | |
4066 return resource_line_offset_; | |
4067 } | |
4068 | |
4069 | |
4070 Handle<Integer> ScriptOrigin::ResourceColumnOffset() const { | |
4071 return resource_column_offset_; | |
4072 } | |
4073 | |
4074 | |
4075 Handle<Boolean> Boolean::New(bool value) { | |
4076 return value ? True() : False(); | |
4077 } | |
4078 | |
4079 | |
4080 void Template::Set(const char* name, v8::Handle<Data> value) { | |
4081 Set(v8::String::New(name), value); | |
4082 } | |
4083 | |
4084 | |
4085 Local<Value> Object::GetInternalField(int index) { | |
4086 #ifndef V8_ENABLE_CHECKS | |
4087 Local<Value> quick_result = UncheckedGetInternalField(index); | |
4088 if (!quick_result.IsEmpty()) return quick_result; | |
4089 #endif | |
4090 return CheckedGetInternalField(index); | |
4091 } | |
4092 | |
4093 | |
4094 Local<Value> Object::UncheckedGetInternalField(int index) { | |
4095 typedef internal::Object O; | |
4096 typedef internal::Internals I; | |
4097 O* obj = *reinterpret_cast<O**>(this); | |
4098 if (I::GetInstanceType(obj) == I::kJSObjectType) { | |
4099 // If the object is a plain JSObject, which is the common case, | |
4100 // we know where to find the internal fields and can return the | |
4101 // value directly. | |
4102 int offset = I::kJSObjectHeaderSize + (internal::kApiPointerSize * index); | |
4103 O* value = I::ReadField<O*>(obj, offset); | |
4104 O** result = HandleScope::CreateHandle(value); | |
4105 return Local<Value>(reinterpret_cast<Value*>(result)); | |
4106 } else { | |
4107 return Local<Value>(); | |
4108 } | |
4109 } | |
4110 | |
4111 | |
4112 void* External::Unwrap(Handle<v8::Value> obj) { | |
4113 #ifdef V8_ENABLE_CHECKS | |
4114 return FullUnwrap(obj); | |
4115 #else | |
4116 return QuickUnwrap(obj); | |
4117 #endif | |
4118 } | |
4119 | |
4120 | |
4121 void* External::QuickUnwrap(Handle<v8::Value> wrapper) { | |
4122 typedef internal::Object O; | |
4123 O* obj = *reinterpret_cast<O**>(const_cast<v8::Value*>(*wrapper)); | |
4124 return internal::Internals::GetExternalPointer(obj); | |
4125 } | |
4126 | |
4127 | |
4128 void* Object::GetPointerFromInternalField(int index) { | |
4129 typedef internal::Object O; | |
4130 typedef internal::Internals I; | |
4131 | |
4132 O* obj = *reinterpret_cast<O**>(this); | |
4133 | |
4134 if (I::GetInstanceType(obj) == I::kJSObjectType) { | |
4135 // If the object is a plain JSObject, which is the common case, | |
4136 // we know where to find the internal fields and can return the | |
4137 // value directly. | |
4138 int offset = I::kJSObjectHeaderSize + (internal::kApiPointerSize * index); | |
4139 O* value = I::ReadField<O*>(obj, offset); | |
4140 return I::GetExternalPointer(value); | |
4141 } | |
4142 | |
4143 return SlowGetPointerFromInternalField(index); | |
4144 } | |
4145 | |
4146 | |
4147 String* String::Cast(v8::Value* value) { | |
4148 #ifdef V8_ENABLE_CHECKS | |
4149 CheckCast(value); | |
4150 #endif | |
4151 return static_cast<String*>(value); | |
4152 } | |
4153 | |
4154 | |
4155 String::ExternalStringResource* String::GetExternalStringResource() const { | |
4156 typedef internal::Object O; | |
4157 typedef internal::Internals I; | |
4158 O* obj = *reinterpret_cast<O**>(const_cast<String*>(this)); | |
4159 String::ExternalStringResource* result; | |
4160 if (I::IsExternalTwoByteString(I::GetInstanceType(obj))) { | |
4161 void* value = I::ReadField<void*>(obj, I::kStringResourceOffset); | |
4162 result = reinterpret_cast<String::ExternalStringResource*>(value); | |
4163 } else { | |
4164 result = NULL; | |
4165 } | |
4166 #ifdef V8_ENABLE_CHECKS | |
4167 VerifyExternalStringResource(result); | |
4168 #endif | |
4169 return result; | |
4170 } | |
4171 | |
4172 | |
4173 bool Value::IsString() const { | |
4174 #ifdef V8_ENABLE_CHECKS | |
4175 return FullIsString(); | |
4176 #else | |
4177 return QuickIsString(); | |
4178 #endif | |
4179 } | |
4180 | |
4181 bool Value::QuickIsString() const { | |
4182 typedef internal::Object O; | |
4183 typedef internal::Internals I; | |
4184 O* obj = *reinterpret_cast<O**>(const_cast<Value*>(this)); | |
4185 if (!I::HasHeapObjectTag(obj)) return false; | |
4186 return (I::GetInstanceType(obj) < I::kFirstNonstringType); | |
4187 } | |
4188 | |
4189 | |
4190 Number* Number::Cast(v8::Value* value) { | |
4191 #ifdef V8_ENABLE_CHECKS | |
4192 CheckCast(value); | |
4193 #endif | |
4194 return static_cast<Number*>(value); | |
4195 } | |
4196 | |
4197 | |
4198 Integer* Integer::Cast(v8::Value* value) { | |
4199 #ifdef V8_ENABLE_CHECKS | |
4200 CheckCast(value); | |
4201 #endif | |
4202 return static_cast<Integer*>(value); | |
4203 } | |
4204 | |
4205 | |
4206 Date* Date::Cast(v8::Value* value) { | |
4207 #ifdef V8_ENABLE_CHECKS | |
4208 CheckCast(value); | |
4209 #endif | |
4210 return static_cast<Date*>(value); | |
4211 } | |
4212 | |
4213 | |
4214 StringObject* StringObject::Cast(v8::Value* value) { | |
4215 #ifdef V8_ENABLE_CHECKS | |
4216 CheckCast(value); | |
4217 #endif | |
4218 return static_cast<StringObject*>(value); | |
4219 } | |
4220 | |
4221 | |
4222 NumberObject* NumberObject::Cast(v8::Value* value) { | |
4223 #ifdef V8_ENABLE_CHECKS | |
4224 CheckCast(value); | |
4225 #endif | |
4226 return static_cast<NumberObject*>(value); | |
4227 } | |
4228 | |
4229 | |
4230 BooleanObject* BooleanObject::Cast(v8::Value* value) { | |
4231 #ifdef V8_ENABLE_CHECKS | |
4232 CheckCast(value); | |
4233 #endif | |
4234 return static_cast<BooleanObject*>(value); | |
4235 } | |
4236 | |
4237 | |
4238 RegExp* RegExp::Cast(v8::Value* value) { | |
4239 #ifdef V8_ENABLE_CHECKS | |
4240 CheckCast(value); | |
4241 #endif | |
4242 return static_cast<RegExp*>(value); | |
4243 } | |
4244 | |
4245 | |
4246 Object* Object::Cast(v8::Value* value) { | |
4247 #ifdef V8_ENABLE_CHECKS | |
4248 CheckCast(value); | |
4249 #endif | |
4250 return static_cast<Object*>(value); | |
4251 } | |
4252 | |
4253 | |
4254 Array* Array::Cast(v8::Value* value) { | |
4255 #ifdef V8_ENABLE_CHECKS | |
4256 CheckCast(value); | |
4257 #endif | |
4258 return static_cast<Array*>(value); | |
4259 } | |
4260 | |
4261 | |
4262 Function* Function::Cast(v8::Value* value) { | |
4263 #ifdef V8_ENABLE_CHECKS | |
4264 CheckCast(value); | |
4265 #endif | |
4266 return static_cast<Function*>(value); | |
4267 } | |
4268 | |
4269 | |
4270 External* External::Cast(v8::Value* value) { | |
4271 #ifdef V8_ENABLE_CHECKS | |
4272 CheckCast(value); | |
4273 #endif | |
4274 return static_cast<External*>(value); | |
4275 } | |
4276 | |
4277 | |
4278 Local<Value> AccessorInfo::Data() const { | |
4279 return Local<Value>(reinterpret_cast<Value*>(&args_[-2])); | |
4280 } | |
4281 | |
4282 | |
4283 Local<Object> AccessorInfo::This() const { | |
4284 return Local<Object>(reinterpret_cast<Object*>(&args_[0])); | |
4285 } | |
4286 | |
4287 | |
4288 Local<Object> AccessorInfo::Holder() const { | |
4289 return Local<Object>(reinterpret_cast<Object*>(&args_[-1])); | |
4290 } | |
4291 | |
4292 | |
4293 /** | |
4294 * \example shell.cc | |
4295 * A simple shell that takes a list of expressions on the | |
4296 * command-line and executes them. | |
4297 */ | |
4298 | |
4299 | |
4300 /** | |
4301 * \example process.cc | |
4302 */ | |
4303 | |
4304 | |
4305 } // namespace v8 | |
4306 | |
4307 | |
4308 #undef V8EXPORT | |
4309 #undef TYPE_CHECK | |
4310 | |
4311 | |
4312 #endif // V8_H_ | |
OLD | NEW |