iOS/Pods/RealmSwift/RealmSwift/ThreadSafeReference.swift

   1 ////////////////////////////////////////////////////////////////////////////
   2 //
   3 // Copyright 2016 Realm Inc.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the "License");
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 // http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17 ////////////////////////////////////////////////////////////////////////////
  18
  19 import Realm
  20
  21 /**
  22  Objects of types which conform to `ThreadConfined` can be managed by a Realm, which will make
  23  them bound to a thread-specific `Realm` instance. Managed objects must be explicitly exported
  24  and imported to be passed between threads.
  25
  26  Managed instances of objects conforming to this protocol can be converted to a thread-safe
  27  reference for transport between threads by passing to the `ThreadSafeReference(to:)` constructor.
  28
  29  Note that only types defined by Realm can meaningfully conform to this protocol, and defining new
  30  classes which attempt to conform to it will not make them work with `ThreadSafeReference`.
  31  */
  32 public protocol ThreadConfined {
  33     // Must also conform to `AssistedObjectiveCBridgeable`
  34
  35     /**
  36      The Realm which manages the object, or `nil` if the object is unmanaged.
  37
  38      Unmanaged objects are not confined to a thread and cannot be passed to methods expecting a
  39      `ThreadConfined` object.
  40      */
  41     var realm: Realm? { get }
  42
  43     /// Indicates if the object can no longer be accessed because it is now invalid.
  44     var isInvalidated: Bool { get }
  45 }
  46
  47 /**
  48  An object intended to be passed between threads containing a thread-safe reference to its
  49  thread-confined object.
  50
  51  To resolve a thread-safe reference on a target Realm on a different thread, pass to
  52  `Realm.resolve(_:)`.
  53
  54  - warning: A `ThreadSafeReference` object must be resolved at most once.
  55             Failing to resolve a `ThreadSafeReference` will result in the source version of the
  56             Realm being pinned until the reference is deallocated.
  57
  58  - note: Prefer short-lived `ThreadSafeReference`s as the data for the version of the source Realm
  59          will be retained until all references have been resolved or deallocated.
  60
  61  - see: `ThreadConfined`
  62  - see: `Realm.resolve(_:)`
  63  */
  64 public class ThreadSafeReference<Confined: ThreadConfined> {
  65     private let swiftMetadata: Any?
  66
  67     /**
  68      Indicates if the reference can no longer be resolved because an attempt to resolve it has
  69      already occurred. References can only be resolved once.
  70      */
  71     public var isInvalidated: Bool { return objectiveCReference.isInvalidated }
  72
  73     private let objectiveCReference: RLMThreadSafeReference<RLMThreadConfined>
  74
  75     /**
  76      Create a thread-safe reference to the thread-confined object.
  77
  78      - parameter threadConfined: The thread-confined object to create a thread-safe reference to.
  79
  80      - note: You may continue to use and access the thread-confined object after passing it to this
  81              constructor.
  82      */
  83     public init(to threadConfined: Confined) {
  84         let bridged = (threadConfined as! AssistedObjectiveCBridgeable).bridged
  85         swiftMetadata = bridged.metadata
  86         objectiveCReference = RLMThreadSafeReference(threadConfined: bridged.objectiveCValue as! RLMThreadConfined)
  87     }
  88
  89     internal func resolve(in realm: Realm) -> Confined? {
  90         guard let objectiveCValue = realm.rlmRealm.__resolve(objectiveCReference) else { return nil }
  91         return ((Confined.self as! AssistedObjectiveCBridgeable.Type).bridging(from: objectiveCValue, with: swiftMetadata) as! Confined)
  92     }
  93 }
  94
  95 extension Realm {
  96     /**
  97      Returns the same object as the one referenced when the `ThreadSafeReference` was first
  98      created, but resolved for the current Realm for this thread. Returns `nil` if this object was
  99      deleted after the reference was created.
 100
 101      - parameter reference: The thread-safe reference to the thread-confined object to resolve in
 102                             this Realm.
 103
 104      - warning: A `ThreadSafeReference` object must be resolved at most once.
 105                 Failing to resolve a `ThreadSafeReference` will result in the source version of the
 106                 Realm being pinned until the reference is deallocated.
 107                 An exception will be thrown if a reference is resolved more than once.
 108
 109      - warning: Cannot call within a write transaction.
 110
 111      - note: Will refresh this Realm if the source Realm was at a later version than this one.
 112
 113      - see: `ThreadSafeReference(to:)`
 114      */
 115     public func resolve<Confined>(_ reference: ThreadSafeReference<Confined>) -> Confined? {
 116         return reference.resolve(in: self)
 117     }
 118 }