1 | /*! |
---|
2 | * @file NDRunLoopMessenger.h |
---|
3 | * |
---|
4 | * @brief Defines the class @c NDRunLoopMessenger |
---|
5 | * |
---|
6 | * @c NDRunLoopMessenger provides a light weight version of distributed objects |
---|
7 | * that only works between threads within the same process. With the advent of |
---|
8 | * Mac OS 10.2 the need for this class has decreased with the introduction of |
---|
9 | * the methods <tt>-[NSObject performSelectorOnMainThread:withObject:waitUntilDone:]</tt> |
---|
10 | * and <tt>-[NSObject performSelectorOnMainThread:withObject:waitUntilDone:modes:]</tt> |
---|
11 | * but it is still useful. |
---|
12 | * |
---|
13 | * @author Nathan Day Copyright © 2002-2003 Nathan Day. All rights reserved. |
---|
14 | * @date Fri Feb 08 2002 |
---|
15 | */ |
---|
16 | |
---|
17 | /*! |
---|
18 | * @brief <tt>NDRunLoopMessenger</tt> exception |
---|
19 | * |
---|
20 | * An exception that can be thrown when sending a message by means of |
---|
21 | * @c NDRunLoopMessenger. This includes any messages forwarded by the proxy |
---|
22 | * returned from the methods <tt>target:</tt> and <tt>target:withResult:</tt>. |
---|
23 | */ |
---|
24 | extern NSString *kSendMessageException; |
---|
25 | |
---|
26 | /*! |
---|
27 | * @brief <tt>NDRunLoopMessenger</tt> exception |
---|
28 | * |
---|
29 | * An exception that can be thrown when sending a message by means of |
---|
30 | * <tt>NDRunLoopMessenger</tt>. This includes any messages forwarded by the |
---|
31 | * proxy returned from the methods <tt>target:</tt> and <tt>target:withResult:</tt>. |
---|
32 | */ |
---|
33 | extern NSString *kConnectionDoesNotExistsException; |
---|
34 | |
---|
35 | /*! |
---|
36 | * @brief Class to provide thread intercommunication |
---|
37 | * |
---|
38 | * A light weight version of distributed objects that only works between threads |
---|
39 | * within the same process. @c NDRunLoopMessenger works by only passing |
---|
40 | * the address of a @c NSInvocation object through a run loop port, this is all |
---|
41 | * that is needed since the object is already within the same process memory space. |
---|
42 | * This means that all the parameters do not need to be serialized. Results are |
---|
43 | * returned simply by waiting on a lock for a message result to be put into the |
---|
44 | * @c NSInvocation. |
---|
45 | */ |
---|
46 | @interface NDRunLoopMessenger : NSObject |
---|
47 | { |
---|
48 | @private |
---|
49 | NSPort * port; |
---|
50 | NSMutableArray * queuedPortMessageArray; |
---|
51 | NSTimer * queuedPortMessageTimer; |
---|
52 | NSRunLoop * targetRunLoop; |
---|
53 | BOOL insideMessageInvocation; |
---|
54 | |
---|
55 | NSTimeInterval messageRetryTimeout; |
---|
56 | NSTimeInterval messageRetry; |
---|
57 | } |
---|
58 | |
---|
59 | /*! |
---|
60 | * @brief Get the @c NDRunLoopMessenger for a thread. |
---|
61 | * |
---|
62 | * If the thread does not have a @c NDRunLoopMessenger then @c nil is returned. |
---|
63 | * |
---|
64 | * @param thread The thread. |
---|
65 | * @return The @c NDRunLoopMessenger for the specified thread. |
---|
66 | */ |
---|
67 | + (NDRunLoopMessenger *)runLoopMessengerForThread:(NSThread *)thread; |
---|
68 | |
---|
69 | /*! |
---|
70 | * @brief Returns the @c NDRunLoopMessenger for the current run loop. |
---|
71 | * |
---|
72 | * If a @c NDRunLoopMessenger has been created for the current run loop then |
---|
73 | * @c runLoopMessengerForCurrentRunLoop will return it otherwise it will |
---|
74 | * create one. |
---|
75 | * |
---|
76 | * @return A @c NDRunLoopMessenger object for the current run loop. |
---|
77 | */ |
---|
78 | + (id)runLoopMessengerForCurrentRunLoop; |
---|
79 | |
---|
80 | /*! |
---|
81 | * @brief Perform a selector. |
---|
82 | * |
---|
83 | * Send a message to the suplied target without waiting for the message to be processed. |
---|
84 | * |
---|
85 | * @param target The target object. |
---|
86 | * @param selector The selector that should be performed on the target object. |
---|
87 | */ |
---|
88 | - (void)target:(id)target performSelector:(SEL)selector; |
---|
89 | |
---|
90 | /*! |
---|
91 | * @brief Perform a selector. |
---|
92 | * |
---|
93 | * Send a message with one object paramter to the suplied target without waiting for |
---|
94 | * the message to be processed. |
---|
95 | * |
---|
96 | * @param target The target object. |
---|
97 | * @param selector The message selector. |
---|
98 | * @param object An object to be passed with the message. |
---|
99 | */ |
---|
100 | - (void)target:(id)target performSelector:(SEL)selector withObject:(id)object; |
---|
101 | |
---|
102 | /*! |
---|
103 | * @brief Perform a selector. |
---|
104 | * |
---|
105 | * Send a message with two object paramters to the suplied target without waiting |
---|
106 | * for the message to be processed. |
---|
107 | * |
---|
108 | * @param target The target object. |
---|
109 | * @param selector The message selector. |
---|
110 | * @param object The first object to be passed with the message. |
---|
111 | * @param anotherObject The second object to be passed with the message. |
---|
112 | */ |
---|
113 | - (void)target:(id)target performSelector:(SEL)selector withObject:(id)object withObject:(id)anotherObject; |
---|
114 | |
---|
115 | - (void)target:(id)aTarget performSelector:(SEL)aSelector withObject:(id)anObject withObject:(id)anotherObject withObject:(id)aThirdObject; |
---|
116 | |
---|
117 | - (void)target:(id)aTarget performSelector:(SEL)aSelector withObject:(id)anObject withObject:(id)anotherObject withObject:(id)aThirdObject withObject:(id)aFourthObject; |
---|
118 | |
---|
119 | - (void)target:(id)aTarget performSelector:(SEL)aSelector withObject:(id)anObject withObject:(id)anotherObject withObject:(id)aThirdObject withObject:(id)aFourthObject withObject:(id)aFifthObject; |
---|
120 | |
---|
121 | /*! |
---|
122 | * @brief Perform a selector. |
---|
123 | * |
---|
124 | * Send a message to the suplied target, the result can be waited for. |
---|
125 | * |
---|
126 | * @param target The target object. |
---|
127 | * @param selector The message selector. |
---|
128 | * @param resultFlag Should the result be waited for and returned. |
---|
129 | * @return The message result if @c resultFlag is @c YES, or @c nil if |
---|
130 | * @c resultFlag is @c NO. |
---|
131 | */ |
---|
132 | - (id)target:(id)target performSelector:(SEL)selector withResult:(BOOL)resultFlag; |
---|
133 | |
---|
134 | /*! |
---|
135 | * @brief Perform a selector. |
---|
136 | * |
---|
137 | * Send a message with one object paramter to the suplied target, the result can be |
---|
138 | * waited for. |
---|
139 | * |
---|
140 | * @param target The target object. |
---|
141 | * @param selector The message selector. |
---|
142 | * @param object An object to be passed with the message. |
---|
143 | * @param resultFlag Should the result be waited for and returned. |
---|
144 | * @return The message result if @c resultFlag is @c YES, or @c nil if |
---|
145 | * @c resultFlag is @c NO. |
---|
146 | */ |
---|
147 | - (id)target:(id)target performSelector:(SEL)selector withObject:(id)object withResult:(BOOL)resultFlag; |
---|
148 | |
---|
149 | /*! |
---|
150 | * @brief Perform a selector. |
---|
151 | * |
---|
152 | * Send a message with two object paramters to the suplied target, the result can be |
---|
153 | * waited for. |
---|
154 | * |
---|
155 | * @param target The target object. |
---|
156 | * @param selector The message selector. |
---|
157 | * @param object The first object to be passed with the message. |
---|
158 | * @param anotherObject The second object to be passed with the message. |
---|
159 | * @param resultFlag Should the result be waited for and returned. |
---|
160 | * @return The message result if @c resultFlag is @c YES, or @c nil if |
---|
161 | * @c resultFlag is @c NO. |
---|
162 | */ |
---|
163 | - (id)target:(id)target performSelector:(SEL)selector withObject:(id)object withObject:(id)anotherObject withResult:(BOOL)resultFlag; |
---|
164 | |
---|
165 | - (id)target:(id)aTarget performSelector:(SEL)aSelector withObject:(id)anObject withObject:(id)anotherObject withObject:(id)aThirdObject withResult:(BOOL)aFlag; |
---|
166 | |
---|
167 | - (id)target:(id)aTarget performSelector:(SEL)aSelector withObject:(id)anObject withObject:(id)anotherObject withObject:(id)aThirdObject withObject:(id)aFourthObject withResult:(BOOL)aFlag; |
---|
168 | |
---|
169 | - (id)target:(id)aTarget performSelector:(SEL)aSelector withObject:(id)anObject withObject:(id)anotherObject withObject:(id)aThirdObject withObject:(id)aFourthObject withObject:(id)aFifthObject withResult:(BOOL)aFlag; |
---|
170 | |
---|
171 | /*! |
---|
172 | * @brief Post a notification. |
---|
173 | * |
---|
174 | * Posts the supplied @c NSNotification object within the receivers run loop. |
---|
175 | * |
---|
176 | * @param notification A @c NSNotification object to be posted. |
---|
177 | */ |
---|
178 | - (void)postNotification:(NSNotification *)notification; |
---|
179 | |
---|
180 | /*! |
---|
181 | * @brief Post a notification. |
---|
182 | * |
---|
183 | * Posts the notification of a supplied name and object within the receivers run loop. |
---|
184 | * |
---|
185 | * @param notificationName The notification name. |
---|
186 | * @param object The object to be posted with the notification. |
---|
187 | * @see @c NSNotification documentation to get more information about the parameters. |
---|
188 | */ |
---|
189 | - (void)postNotificationName:(NSString *)notificationName object:(id)object; |
---|
190 | |
---|
191 | /*! |
---|
192 | * @brief Post a notification. |
---|
193 | * |
---|
194 | * Posts the notification of a supplied name, object and uder info within the receivers |
---|
195 | * run loop. |
---|
196 | * |
---|
197 | * @param notificationName The notification name. |
---|
198 | * @param object The object to be posted with the notification. |
---|
199 | * @param userInfo A @c NSDictionary of user info. |
---|
200 | * @see @c NSNotification documentation to get more information about the parameters. |
---|
201 | */ |
---|
202 | - (void)postNotificationName:(NSString *)notificationName object:(id)object userInfo:(NSDictionary *)userInfo; |
---|
203 | |
---|
204 | /*! |
---|
205 | * @brief Invoke and invocation. |
---|
206 | * |
---|
207 | * Invokes the passed in @c NSInvocation within the receivers run loop. |
---|
208 | * |
---|
209 | * @param invocation The @c NSInvocation |
---|
210 | * @param resultFlag Should the result be waited for and returned. |
---|
211 | * @return The invocation result if @c resultFlag is @c YES, or @c nil if |
---|
212 | * @c resultFlag is @c NO. |
---|
213 | */ |
---|
214 | - (void)messageInvocation:(NSInvocation *)invocation withResult:(BOOL)resultFlag; |
---|
215 | |
---|
216 | /*! |
---|
217 | * @brief Get a target proxy. |
---|
218 | * |
---|
219 | * Returns a object that acts as a proxy, forwarding all messages it receives to the |
---|
220 | * supplied target. All messages sent to the target return immediately without waiting |
---|
221 | * for the result. |
---|
222 | * |
---|
223 | * @param target The target object. |
---|
224 | * @return The proxy object. |
---|
225 | */ |
---|
226 | - (id)target:(id)target; |
---|
227 | |
---|
228 | /*! |
---|
229 | * @brief Get a target proxy. |
---|
230 | * |
---|
231 | * Returns a object that acts as a proxy, forwarding all messages it receives to the |
---|
232 | * supplied target. |
---|
233 | * |
---|
234 | * @param target The target object. |
---|
235 | * @param resultFlag Should all results be waited for and returned. |
---|
236 | * @return The proxy object. |
---|
237 | */ |
---|
238 | - (id)target:(id)target withResult:(BOOL)resultFlag; |
---|
239 | |
---|
240 | - (id)targetFromNoRunLoop:(id)aTarget; |
---|
241 | |
---|
242 | - (void)setMessageRetryTimeout:(NSTimeInterval)inMessageRetryTimeout; |
---|
243 | - (void)setMessageRetry:(NSTimeInterval)inMessageRetry; |
---|
244 | |
---|
245 | - (NSRunLoop *)targetRunLoop; |
---|
246 | |
---|
247 | @end |
---|