1 ////////////////////////////////////////////////////////////////////////////
3 // Copyright 2016 Realm Inc.
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
9 // http://www.apache.org/licenses/LICENSE-2.0
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.
17 ////////////////////////////////////////////////////////////////////////////
19 #import <Foundation/Foundation.h>
23 NS_ASSUME_NONNULL_BEGIN
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.
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.
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`.
37 @protocol RLMThreadConfined <NSObject>
38 // Conformance to the `RLMThreadConfined_Private` protocol will be enforced at runtime.
41 The Realm which manages the object, or `nil` if the object is unmanaged.
43 Unmanaged objects are not confined to a thread and cannot be passed to methods expecting a
44 `RLMThreadConfined` object.
46 @property (nonatomic, readonly, nullable) RLMRealm *realm;
48 /// Indicates if the object can no longer be accessed because it is now invalid.
49 @property (nonatomic, readonly, getter = isInvalidated) BOOL invalidated;
54 An object intended to be passed between threads containing a thread-safe reference to its
55 thread-confined object.
57 To resolve a thread-safe reference on a target Realm on a different thread, pass to
58 `-[RLMRealm resolveThreadSafeReference:]`.
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.
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.
67 @see `RLMThreadConfined`
68 @see `-[RLMRealm resolveThreadSafeReference:]`
70 @interface RLMThreadSafeReference<__covariant Confined : id<RLMThreadConfined>> : NSObject
73 Create a thread-safe reference to the thread-confined object.
75 @param threadConfined The thread-confined object to create a thread-safe reference to.
77 @note You may continue to use and access the thread-confined object after passing it to this
80 + (instancetype)referenceWithThreadConfined:(Confined)threadConfined;
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.
86 @property (nonatomic, readonly, getter = isInvalidated) BOOL invalidated;
88 #pragma mark - Unavailable Methods
91 `-[RLMThreadSafeReference init]` is not available because `RLMThreadSafeReference` cannot be
92 created directly. `RLMThreadSafeReference` instances must be obtained by calling
93 `-[RLMRealm resolveThreadSafeReference:]`.
95 - (instancetype)init __attribute__((unavailable("RLMThreadSafeReference cannot be created directly")));
98 `-[RLMThreadSafeReference new]` is not available because `RLMThreadSafeReference` cannot be
99 created directly. `RLMThreadSafeReference` instances must be obtained by calling
100 `-[RLMRealm resolveThreadSafeReference:]`.
102 + (instancetype)new __attribute__((unavailable("RLMThreadSafeReference cannot be created directly")));
106 NS_ASSUME_NONNULL_END