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  #if defined(DARLING) && __i386__
 31  #import "JSLock.h"
 32  #endif
 33  
 34  /*!
 35  @interface
 36  @discussion An instance of JSVirtualMachine represents a single JavaScript "object space"
 37   or set of execution resources. Thread safety is supported by locking the
 38   virtual machine, with concurrent JavaScript execution supported by allocating
 39   separate instances of JSVirtualMachine.
 40  
 41   A virtual machine may need to run deferred tasks on a run loop, such as garbage collection
 42   or resolving WebAssembly compilations. By default, a virtual machine will use the run loop
 43   of the thread it was initialized on. Currently, there is no API to change a
 44   JSVirtualMachine's run loop once it has been initialized.
 45  */
 46  NS_CLASS_AVAILABLE(10_9, 7_0)
 47  #if defined(DARLING) && __i386__
 48  @interface JSVirtualMachine : NSObject {
 49      JSContextGroupRef m_group;
 50      Lock m_externalDataMutex;
 51      NSMapTable *m_contextCache;
 52      NSMapTable *m_externalObjectGraph;
 53      NSMapTable *m_externalRememberedSet;
 54  }
 55  #else
 56  @interface JSVirtualMachine : NSObject
 57  #endif
 58  
 59  /*!
 60  @methodgroup Creating New Virtual Machines
 61  */
 62  /*!
 63  @method
 64  @abstract Create a new JSVirtualMachine.
 65  */
 66  - (instancetype)init;
 67  
 68  /*!
 69  @methodgroup Memory Management
 70  */
 71  /*!
 72  @method
 73  @abstract Notify the JSVirtualMachine of an external object relationship.
 74  @discussion Allows clients of JSVirtualMachine to make the JavaScript runtime aware of 
 75   arbitrary external Objective-C object graphs. The runtime can then use 
 76   this information to retain any JavaScript values that are referenced 
 77   from somewhere in said object graph.
 78  
 79   For correct behavior clients must make their external object graphs 
 80   reachable from within the JavaScript runtime. If an Objective-C object is 
 81   reachable from within the JavaScript runtime, all managed references 
 82   transitively reachable from it as recorded using
 83   -addManagedReference:withOwner: will be scanned by the garbage collector.
 84  @param object The object that the owner points to.
 85  @param owner The object that owns the pointed to object.
 86  */ 
 87  - (void)addManagedReference:(id)object withOwner:(id)owner;
 88  
 89  /*!
 90  @method
 91  @abstract Notify the JSVirtualMachine that a previous object relationship no longer exists.
 92  @discussion The JavaScript runtime will continue to scan any references that were
 93   reported to it by -addManagedReference:withOwner: until those references are removed.
 94  @param object The object that was formerly owned.
 95  @param owner The former owner.
 96  */
 97  - (void)removeManagedReference:(id)object withOwner:(id)owner;
 98  
 99  @end
100  
101  #endif