added iOS source code
[wl-app.git] / 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