root/Trunk/Adium.framework/Versions/A/Headers/NDRunLoopMessenger.h @ 2

Revision 2, 9.0 KB (checked in by jon, 16 years ago)

Initial commit of skeletal project.

Line 
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 &copy; 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 */
24extern 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 */
33extern 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
Note: See TracBrowser for help on using the browser.