iOS/Pods/Realm/include/RLMThreadSafeReference.h

   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 <Foundation/Foundation.h>
  20
  21 @class RLMRealm;
  22
  23 NS_ASSUME_NONNULL_BEGIN
  24
  25 /**
  26  Objects of types which conform to `RLMThreadConfined` can be managed by a Realm, which will make
  27  them bound to a thread-specific `RLMRealm` instance. Managed objects must be explicitly exported
  28  and imported to be passed between threads.
  29
  30  Managed instances of objects conforming to this protocol can be converted to a thread-safe
  31  reference for transport between threads by passing to the
  32  `+[RLMThreadSafeReference referenceWithThreadConfined:]` constructor.
  33
  34  Note that only types defined by Realm can meaningfully conform to this protocol, and defining new
  35  classes which attempt to conform to it will not make them work with `RLMThreadSafeReference`.
  36  */
  37 @protocol RLMThreadConfined <NSObject>
  38 // Conformance to the `RLMThreadConfined_Private` protocol will be enforced at runtime.
  39
  40 /**
  41  The Realm which manages the object, or `nil` if the object is unmanaged.
  42
  43  Unmanaged objects are not confined to a thread and cannot be passed to methods expecting a
  44  `RLMThreadConfined` object.
  45  */
  46 @property (nonatomic, readonly, nullable) RLMRealm *realm;
  47
  48 /// Indicates if the object can no longer be accessed because it is now invalid.
  49 @property (nonatomic, readonly, getter = isInvalidated) BOOL invalidated;
  50
  51 @end
  52
  53 /**
  54  An object intended to be passed between threads containing a thread-safe reference to its
  55  thread-confined object.
  56
  57  To resolve a thread-safe reference on a target Realm on a different thread, pass to
  58  `-[RLMRealm resolveThreadSafeReference:]`.
  59
  60  @warning A `RLMThreadSafeReference` object must be resolved at most once.
  61           Failing to resolve a `RLMThreadSafeReference` will result in the source version of the
  62           Realm being pinned until the reference is deallocated.
  63
  64  @note Prefer short-lived `RLMThreadSafeReference`s as the data for the version of the source Realm
  65        will be retained until all references have been resolved or deallocated.
  66
  67  @see `RLMThreadConfined`
  68  @see `-[RLMRealm resolveThreadSafeReference:]`
  69  */
  70 @interface RLMThreadSafeReference<__covariant Confined : id<RLMThreadConfined>> : NSObject
  71
  72 /**
  73  Create a thread-safe reference to the thread-confined object.
  74
  75  @param threadConfined The thread-confined object to create a thread-safe reference to.
  76
  77  @note You may continue to use and access the thread-confined object after passing it to this
  78        constructor.
  79  */
  80 + (instancetype)referenceWithThreadConfined:(Confined)threadConfined;
  81
  82 /**
  83  Indicates if the reference can no longer be resolved because an attempt to resolve it has already
  84  occurred. References can only be resolved once.
  85  */
  86 @property (nonatomic, readonly, getter = isInvalidated) BOOL invalidated;
  87
  88 #pragma mark - Unavailable Methods
  89
  90 /**
  91  `-[RLMThreadSafeReference init]` is not available because `RLMThreadSafeReference` cannot be
  92  created directly. `RLMThreadSafeReference` instances must be obtained by calling
  93  `-[RLMRealm resolveThreadSafeReference:]`.
  94  */
  95 - (instancetype)init __attribute__((unavailable("RLMThreadSafeReference cannot be created directly")));
  96
  97 /**
  98  `-[RLMThreadSafeReference new]` is not available because `RLMThreadSafeReference` cannot be
  99  created directly. `RLMThreadSafeReference` instances must be obtained by calling
 100  `-[RLMRealm resolveThreadSafeReference:]`.
 101  */
 102 + (instancetype)new __attribute__((unavailable("RLMThreadSafeReference cannot be created directly")));
 103
 104 @end
 105
 106 NS_ASSUME_NONNULL_END