1/*
2 * Copyright (C) 2013 Apple Inc. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 * 1. Redistributions of source code must retain the above copyright
8 *    notice, this list of conditions and the following disclaimer.
9 * 2. Redistributions in binary form must reproduce the above copyright
10 *    notice, this list of conditions and the following disclaimer in the
11 *    documentation and/or other materials provided with the distribution.
12 *
13 * THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
14 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE INC. OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
18 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
19 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
20 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
21 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
22 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
23 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
24 */
25
26#import <JavaScriptCore/JavaScriptCore.h>
27
28#if JSC_OBJC_API_ENABLED
29
30/*!
31@interface
32@discussion An instance of JSVirtualMachine represents a single JavaScript "object space"
33 or set of execution resources. Thread safety is supported by locking the
34 virtual machine, with concurrent JavaScript execution supported by allocating
35 separate instances of JSVirtualMachine.
36*/
37#ifndef JSC_OBJC_API_AVAILABLE_MAC_OS_X_1080
38NS_CLASS_AVAILABLE(10_9, 7_0)
39#else
40OBJC_VISIBLE
41#endif
42@interface JSVirtualMachine : NSObject
43
44/*!
45@methodgroup Creating New Virtual Machines
46*/
47/*!
48@method
49@abstract Create a new JSVirtualMachine.
50*/
51- (instancetype)init;
52
53/*!
54@methodgroup Memory Management
55*/
56/*!
57@method
58@abstract Notify the JSVirtualMachine of an external object relationship.
59@discussion Allows clients of JSVirtualMachine to make the JavaScript runtime aware of
60 arbitrary external Objective-C object graphs. The runtime can then use
61 this information to retain any JavaScript values that are referenced
62 from somewhere in said object graph.
63
64 For correct behavior clients must make their external object graphs
65 reachable from within the JavaScript runtime. If an Objective-C object is
66 reachable from within the JavaScript runtime, all managed references
67 transitively reachable from it as recorded using
68 -addManagedReference:withOwner: will be scanned by the garbage collector.
69@param object The object that the owner points to.
70@param owner The object that owns the pointed to object.
71*/
72- (void)addManagedReference:(id)object withOwner:(id)owner;
73
74/*!
75@method
76@abstract Notify the JSVirtualMachine that a previous object relationship no longer exists.
77@discussion The JavaScript runtime will continue to scan any references that were
78 reported to it by -addManagedReference:withOwner: until those references are removed.
79@param object The object that was formerly owned.
80@param owner The former owner.
81*/
82- (void)removeManagedReference:(id)object withOwner:(id)owner;
83
84@end
85
86#endif
87