1 | /* |
2 | * Copyright (c) 2000-2016 Apple Inc. All rights reserved. |
3 | * |
4 | * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ |
5 | * |
6 | * This file contains Original Code and/or Modifications of Original Code |
7 | * as defined in and that are subject to the Apple Public Source License |
8 | * Version 2.0 (the 'License'). You may not use this file except in |
9 | * compliance with the License. The rights granted to you under the License |
10 | * may not be used to create, or enable the creation or redistribution of, |
11 | * unlawful or unlicensed copies of an Apple operating system, or to |
12 | * circumvent, violate, or enable the circumvention or violation of, any |
13 | * terms of an Apple operating system software license agreement. |
14 | * |
15 | * Please obtain a copy of the License at |
16 | * http://www.opensource.apple.com/apsl/ and read it before using this file. |
17 | * |
18 | * The Original Code and all software distributed under the License are |
19 | * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER |
20 | * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, |
21 | * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, |
22 | * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. |
23 | * Please see the License for the specific language governing rights and |
24 | * limitations under the License. |
25 | * |
26 | * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ |
27 | */ |
28 | |
29 | #ifndef _OS_OSORDEREDSET_H |
30 | #define _OS_OSORDEREDSET_H |
31 | |
32 | #include <libkern/c++/OSCollection.h> |
33 | #include <libkern/OSTypes.h> |
34 | |
35 | class OSOffset; |
36 | |
37 | /*! |
38 | * @header |
39 | * |
40 | * @abstract |
41 | * This header declares the OSOrderedSet collection class. |
42 | */ |
43 | |
44 | |
45 | /*! |
46 | * @class OSOrderedSet |
47 | * |
48 | * @abstract |
49 | * OSOrderedSet provides an ordered set store of objects. |
50 | * |
51 | * @discussion |
52 | * OSOrderedSet is a container for Libkern C++ objects |
53 | * (those derived from |
54 | * @link //apple_ref/doc/class/OSMetaClassBase OSMetaClassBase@/link, |
55 | * in particular @link //apple_ref/doc/class/OSObject OSObject@/link). |
56 | * Storage and access follow ordered set logic. |
57 | * A given object is stored in the set only once, but you can: |
58 | * <ul> |
59 | * <li>Define a sorting function for automated ordering |
60 | * (upon addition only)</li> |
61 | * <li>Manually insert new objects in the set (overriding sorting)</li> |
62 | * <li>Add and remove objects in the set</li> |
63 | * <li>Test whether the set contains a particular object</li> |
64 | * <li>Get the object stored at a particular index.</li> |
65 | * </ul> |
66 | * |
67 | * Note that automated ordering is performed only upon addition of objects |
68 | * and depends on the existing objects being properly sorted. |
69 | * There is no function to re-sort the contents of an OSOrderedSet |
70 | * or to change the ordering function. |
71 | * In general, you should either use the one ordered-insertion function, |
72 | * or the indexed-insertion functions, and not mix the two. |
73 | * |
74 | * As with all Libkern collection classes, |
75 | * OSOrderedSet retains objects added to it, |
76 | * and releases objects removed from it. |
77 | * An OSOrderedSet also grows as necessary to accommodate new objects, |
78 | * <i>unlike</i> Core Foundation collections (it does not, however, shrink). |
79 | * |
80 | * <b>Use Restrictions</b> |
81 | * |
82 | * With very few exceptions in the I/O Kit, all Libkern-based C++ |
83 | * classes, functions, and macros are <b>unsafe</b> |
84 | * to use in a primary interrupt context. |
85 | * Consult the I/O Kit documentation related to primary interrupts |
86 | * for more information. |
87 | * |
88 | * OSOrderedSet provides no concurrency protection; |
89 | * it's up to the usage context to provide any protection necessary. |
90 | * Some portions of the I/O Kit, such as |
91 | * @link //apple_ref/doc/class/IORegistryEntry IORegistryEntry@/link, |
92 | * handle synchronization via defined member functions for setting |
93 | * properties. |
94 | */ |
95 | class OSOrderedSet : public OSCollection |
96 | { |
97 | OSDeclareDefaultStructors(OSOrderedSet) |
98 | |
99 | public: |
100 | /*! |
101 | * @typedef OSOrderFunction |
102 | * |
103 | * @abstract |
104 | * The sorting function used by an OSOrderedSet to order objects. |
105 | * |
106 | * @param obj1 An object from the ordered set. May be <code>NULL</code>. |
107 | * @param obj2 The object being ordered within the ordered set. |
108 | * May be <code>NULL</code>. |
109 | * @param context A pointer to a user-provided context. May be <code>NULL</code>. |
110 | * |
111 | * @result |
112 | * A comparison result of the object: |
113 | * <ul> |
114 | * <li>a negative value if obj2 should precede obj1,</li> |
115 | * <li>a positive value if obj1 should precede obj2,</li> |
116 | * <li>and 0 if obj1 and obj2 have an equivalent ordering.</li> |
117 | * </ul> |
118 | */ |
119 | typedef SInt32 (*OSOrderFunction)(const OSMetaClassBase * obj1, |
120 | const OSMetaClassBase * obj2, |
121 | void * context); |
122 | |
123 | protected: |
124 | struct _Element * array; |
125 | OSOrderFunction ordering; |
126 | void * orderingRef; |
127 | unsigned int count; |
128 | unsigned int capacity; |
129 | unsigned int capacityIncrement; |
130 | |
131 | struct ExpansionData { }; |
132 | |
133 | /* Reserved for future use. (Internal use only) */ |
134 | ExpansionData *reserved; |
135 | |
136 | protected: |
137 | /* OSCollectionIterator interfaces. */ |
138 | virtual unsigned int iteratorSize() const APPLE_KEXT_OVERRIDE; |
139 | virtual bool initIterator(void *iterator) const APPLE_KEXT_OVERRIDE; |
140 | virtual bool getNextObjectForIterator(void *iterator, OSObject **ret) const APPLE_KEXT_OVERRIDE; |
141 | |
142 | public: |
143 | |
144 | /*! |
145 | * @function withCapacity |
146 | * |
147 | * @abstract |
148 | * Creates and initializes an empty OSOrderedSet. |
149 | * |
150 | * @param capacity The initial storage capacity |
151 | * of the new ordered set object. |
152 | * @param orderFunc A C function that implements the sorting algorithm |
153 | * for the set. |
154 | * @param orderingContext An ordering context, |
155 | * which is passed to <code>orderFunc</code>. |
156 | * @result |
157 | * An empty instance of OSOrderedSet |
158 | * with a retain count of 1; |
159 | * <code>NULL</code> on failure. |
160 | * |
161 | * @discussion |
162 | * <code>capacity</code> must be nonzero. |
163 | * The new OSOrderedSet will grow as needed |
164 | * to accommodate more key/object pairs |
165 | * (<i>unlike</i> Core Foundation collections, |
166 | * for which the initial capacity is a hard limit). |
167 | * |
168 | * If <code>orderFunc</code> is provided, it is used by |
169 | * <code>@link |
170 | * //apple_ref/cpp/instm/OSOrderedSet/setObject/virtualbool/(constOSMetaClassBase*) |
171 | * setObject(const OSMetaClassBase *)@/link</code> |
172 | * to determine where to insert a new object. |
173 | * Other object-setting functions ignore ordering. |
174 | * |
175 | * <code>orderingContext</code> is not retained or otherwise memory-managed |
176 | * by the ordered set. |
177 | * If it needs to be deallocated, |
178 | * you must track references to it and the ordered set |
179 | * in order to deallocate it appropriately. |
180 | * See |
181 | * <code>@link getOrderingRef getOrderingRef@/link</code>. |
182 | */ |
183 | static OSOrderedSet * withCapacity( |
184 | unsigned int capacity, |
185 | OSOrderFunction orderFunc = 0, |
186 | void * orderingContext = 0); |
187 | |
188 | |
189 | /*! |
190 | * @function initWithCapacity |
191 | * |
192 | * @abstract |
193 | * Initializes a new instance of OSOrderedSet. |
194 | * |
195 | * @param capacity The initial storage capacity |
196 | * of the new ordered set object. |
197 | * @param orderFunc A C function that implements the sorting algorithm |
198 | * for the set. |
199 | * @param orderingContext An ordering context, |
200 | * which is passed to <code>orderFunc</code>. |
201 | * |
202 | * @result |
203 | * <code>true</code> on success, <code>false</code> on failure. |
204 | * |
205 | * @discussion |
206 | * Not for general use. Use the static instance creation method |
207 | * <code>@link |
208 | * //apple_ref/cpp/clm/OSOrderedSet/withCapacity/staticOSOrderedSet*\/(unsignedint,OSOrderFunction,void*) |
209 | * withCapacity@/link</code> |
210 | * instead. |
211 | * |
212 | * <code>capacity</code> must be nonzero. |
213 | * The new set will grow as needed to accommodate more key/object pairs |
214 | * (<i>unlike</i> Core Foundation collections, |
215 | * for which the initial capacity is a hard limit). |
216 | * |
217 | * If <code>orderFunc</code> is provided, it is used by |
218 | * <code>@link |
219 | * //apple_ref/cpp/instm/OSOrderedSet/setObject/virtualbool/(constOSMetaClassBase*) |
220 | * setObject(const OSMetaClassBase *)@/link</code> |
221 | * to determine where to insert a new object. |
222 | * Other object-setting functions ignore ordering. |
223 | * |
224 | * <code>orderingContext</code> is not retained or otherwise memory-managed |
225 | * by the ordered set. |
226 | * If it needs to be deallocated, |
227 | * you must track references to it and the ordered set |
228 | * in order to deallocate it appropriately. |
229 | * See |
230 | * <code>@link getOrderingRef getOrderingRef@/link</code>. |
231 | */ |
232 | virtual bool initWithCapacity( |
233 | unsigned int capacity, |
234 | OSOrderFunction orderFunc = 0, |
235 | void * orderingContext = 0); |
236 | |
237 | |
238 | /*! |
239 | * @function free |
240 | * |
241 | * @abstract |
242 | * Deallocatesand releases any resources |
243 | * used by the OSOrderedSet instance. |
244 | * |
245 | * @discussion |
246 | * This function should not be called directly; |
247 | * use |
248 | * <code>@link |
249 | * //apple_ref/cpp/instm/OSObject/release/virtualvoid/() |
250 | * release@/link</code> |
251 | * instead. |
252 | */ |
253 | virtual void free() APPLE_KEXT_OVERRIDE; |
254 | |
255 | |
256 | /*! |
257 | * @function getCount |
258 | * |
259 | * @abstract |
260 | * Returns the current number of objects within the ordered set. |
261 | * |
262 | * @result |
263 | * The current number of objects within the ordered set. |
264 | */ |
265 | virtual unsigned int getCount() const APPLE_KEXT_OVERRIDE; |
266 | |
267 | |
268 | /*! |
269 | * @function getCapacity |
270 | * |
271 | * @abstract |
272 | * Returns the number of objects the ordered set |
273 | * can store without reallocating. |
274 | * |
275 | * @result |
276 | * The number objects the ordered set |
277 | * can store without reallocating. |
278 | * |
279 | * @discussion |
280 | * OSOrderedSet objects grow when full to accommodate additional objects. |
281 | * See |
282 | * <code>@link |
283 | * //apple_ref/cpp/instm/OSOrderedSet/getCapacityIncrement/virtualunsignedint/() |
284 | * getCapacityIncrement@/link</code> |
285 | * and |
286 | * <code>@link |
287 | * //apple_ref/cpp/instm/OSOrderedSet/ensureCapacity/virtualunsignedint/(unsignedint) |
288 | * ensureCapacity@/link</code>. |
289 | */ |
290 | virtual unsigned int getCapacity() const APPLE_KEXT_OVERRIDE; |
291 | |
292 | |
293 | /*! |
294 | * @function getCapacityIncrement |
295 | * |
296 | * @abstract |
297 | * Returns the storage increment of the ordered set. |
298 | * |
299 | * @result |
300 | * The storage increment of the ordered set. |
301 | * |
302 | * @discussion |
303 | * An OSOrderedSet allocates storage for objects in multiples |
304 | * of the capacity increment. |
305 | */ |
306 | virtual unsigned int getCapacityIncrement() const APPLE_KEXT_OVERRIDE; |
307 | |
308 | |
309 | /*! |
310 | * @function setCapacityIncrement |
311 | * |
312 | * @abstract |
313 | * Sets the storage increment of the ordered set. |
314 | * |
315 | * @result |
316 | * The new storage increment of the ordered set, |
317 | * which may be different from the number requested. |
318 | * |
319 | * @discussion |
320 | * An OSOrderedSet allocates storage for objects in multiples |
321 | * of the capacity increment. |
322 | * Calling this function does not immediately reallocate storage. |
323 | */ |
324 | virtual unsigned int setCapacityIncrement(unsigned increment) APPLE_KEXT_OVERRIDE; |
325 | |
326 | |
327 | /*! |
328 | * @function ensureCapacity |
329 | * |
330 | * @abstract |
331 | * Ensures the set has enough space |
332 | * to store the requested number of distinct objects. |
333 | * |
334 | * @param newCapacity The total number of distinct objects the ordered set |
335 | * should be able to store. |
336 | * |
337 | * @result |
338 | * The new capacity of the ordered set, |
339 | * which may be different from the number requested |
340 | * (if smaller, reallocation of storage failed). |
341 | * |
342 | * @discussion |
343 | * This function immediately resizes the ordered set, if necessary, |
344 | * to accommodate at least <code>newCapacity</code> distinct objects. |
345 | * If <code>newCapacity</code> is not greater than the current capacity, |
346 | * or if an allocation error occurs, the original capacity is returned. |
347 | * |
348 | * There is no way to reduce the capacity of an OSOrderedSet. |
349 | */ |
350 | virtual unsigned int ensureCapacity(unsigned int newCapacity) APPLE_KEXT_OVERRIDE; |
351 | |
352 | |
353 | /*! |
354 | * @function flushCollection |
355 | * |
356 | * @abstract |
357 | * Removes and releases all objects within the ordered set. |
358 | * |
359 | * @discussion |
360 | * The ordered set's capacity (and therefore direct memory consumption) |
361 | * is not reduced by this function. |
362 | */ |
363 | virtual void flushCollection() APPLE_KEXT_OVERRIDE; |
364 | |
365 | |
366 | /*! |
367 | * @function setObject |
368 | * |
369 | * @abstract |
370 | * Adds an object to the OSOrderedSet if it is not already present, |
371 | * storing it in sorted order if there is an order function. |
372 | * |
373 | * @param anObject The OSMetaClassBase-derived object to be added |
374 | * to the ordered set. |
375 | * @result |
376 | * <code>true</code> if <code>anObject</code> was successfully |
377 | * added to the ordered set, <code>false</code> otherwise |
378 | * (including if it was already in the ordered set). |
379 | * |
380 | * @discussion |
381 | * The set adds storage to accomodate the new object, if necessary. |
382 | * If successfully added, the object is retained. |
383 | * |
384 | * If <code>anObject</code> is not already in the ordered set |
385 | * and there is an order function, |
386 | * this function loops through the existing objects, |
387 | * calling the @link OSOrderFunction order function@/link |
388 | * with arguments each existingObject, <code>anObject</code>, |
389 | * and the ordering context |
390 | * (or <code>NULL</code> if none was set), |
391 | * until the order function returns |
392 | * a value <i>greater than</i> or equal to 0. |
393 | * It then inserts <code>anObject</code> at the index of the existing object. |
394 | * |
395 | * If there is no order function, the object is inserted at index 0. |
396 | * |
397 | * A <code>false</code> return value can mean either |
398 | * that <code>anObject</code> is already present in the set, |
399 | * or that a memory allocation failure occurred. |
400 | * If you need to know whether the object |
401 | * is already present, use |
402 | * <code>@link |
403 | * //apple_ref/cpp/instm/OSOrderedSet/containsObject/virtualbool/(constOSMetaClassBase*) |
404 | * containsObject(const OSMetaClassBase *)@/link</code>. |
405 | */ |
406 | virtual bool setObject(const OSMetaClassBase * anObject); |
407 | |
408 | |
409 | /*! |
410 | * @function setFirstObject |
411 | * |
412 | * @abstract |
413 | * Adds an object to the OSOrderedSet at index 0 |
414 | * if it is not already present. |
415 | * |
416 | * @param anObject The OSMetaClassBase-derived object |
417 | * to be added to the ordered set. |
418 | * @result |
419 | * <code>true</code> if <code>anObject</code> was successfully added |
420 | * to the ordered set, <code>false</code> otherwise |
421 | * (including if it was already in the ordered set at any index). |
422 | * |
423 | * @discussion |
424 | * The set adds storage to accomodate the new object, if necessary. |
425 | * If successfully added, the object is retained. |
426 | * |
427 | * This function ignores any ordering function of the ordered set, |
428 | * and can disrupt the automatic sorting mechanism. |
429 | * Only call this function if you are managing the ordered set directly. |
430 | * |
431 | * A <code>false</code> return value can mean either that <code>anObject</code> |
432 | * is already present in the set, |
433 | * or that a memory allocation failure occurred. |
434 | * If you need to know whether the object |
435 | * is already present, use |
436 | * <code>@link |
437 | * //apple_ref/cpp/instm/OSOrderedSet/containsObject/virtualbool/(constOSMetaClassBase*) |
438 | * containsObject(const OSMetaClassBase *)@/link</code>. |
439 | */ |
440 | virtual bool setFirstObject(const OSMetaClassBase * anObject); |
441 | |
442 | |
443 | /*! |
444 | * @function setLastObject |
445 | * |
446 | * @abstract |
447 | * Adds an object at the end of the OSOrderedSet |
448 | * if it is not already present. |
449 | * |
450 | * @param anObject The OSMetaClassBase-derived object to be added |
451 | * to the ordered set. |
452 | * @result |
453 | * <code>true</code> if <code>anObject</code> was successfully added |
454 | * to the ordered set, <code>false</code> otherwise |
455 | * (including if it was already in the ordered set at any index). |
456 | * |
457 | * @discussion |
458 | * The set adds storage to accomodate the new object, if necessary. |
459 | * If successfully added, the object is retained. |
460 | * |
461 | * This function ignores any ordering function of the ordered set, |
462 | * and can disrupt the automatic sorting mechanism. |
463 | * Only call this function if you are managing the ordered set directly. |
464 | * |
465 | * A <code>false</code> return value can mean either that <code>anObject</code> |
466 | * is already present in the set, |
467 | * or that a memory allocation failure occurred. |
468 | * If you need to know whether the object |
469 | * is already present, use |
470 | * <code>@link |
471 | * //apple_ref/cpp/instm/OSOrderedSet/containsObject/virtualbool/(constOSMetaClassBase*) |
472 | * containsObject(const OSMetaClassBase *)@/link</code>. |
473 | */ |
474 | virtual bool setLastObject(const OSMetaClassBase * anObject); |
475 | |
476 | |
477 | /*! |
478 | * @function removeObject |
479 | * |
480 | * @abstract |
481 | * Removes an object from the ordered set. |
482 | * |
483 | * @param anObject The OSMetaClassBase-derived object |
484 | * to be removed from the ordered set. |
485 | * |
486 | * @discussion |
487 | * The object removed from the ordered set is released. |
488 | */ |
489 | virtual void removeObject(const OSMetaClassBase * anObject); |
490 | |
491 | |
492 | /*! |
493 | * @function containsObject |
494 | * |
495 | * @abstract |
496 | * Checks the ordered set for the presence of an object. |
497 | * |
498 | * @param anObject The OSMetaClassBase-derived object to check for |
499 | * in the ordered set. |
500 | * |
501 | * @result |
502 | * <code>true</code> if <code>anObject</code> is present |
503 | * within the ordered set, <code>false</code> otherwise. |
504 | * |
505 | * @discussion |
506 | * Pointer equality is used. |
507 | * This function returns <code>false</code> if passed <code>NULL</code>. |
508 | */ |
509 | virtual bool containsObject(const OSMetaClassBase * anObject) const; |
510 | |
511 | |
512 | /*! |
513 | * @function member |
514 | * |
515 | * @abstract |
516 | * Checks the ordered set for the presence of an object. |
517 | * |
518 | * @param anObject The OSMetaClassBase-derived object to check for |
519 | * in the ordered set. |
520 | * |
521 | * @result |
522 | * <code>true</code> if <code>anObject</code> is present |
523 | * within the ordered set, <code>false</code> otherwise. |
524 | * |
525 | * @discussion |
526 | * Pointer equality is used. |
527 | * Returns <code>false</code> if passed <code>NULL</code>. |
528 | * |
529 | * <code>@link |
530 | * //apple_ref/cpp/instm/OSOrderedSet/containsObject/virtualbool/(constOSMetaClassBase*) |
531 | * containsObject(const OSMetaClassBase *)@/link</code> |
532 | * checks for <code>NULL</code> before scanning the contents, |
533 | * and is therefore more efficient than this function. |
534 | */ |
535 | virtual bool member(const OSMetaClassBase * anObject) const; |
536 | |
537 | |
538 | /*! |
539 | * @function getFirstObject |
540 | * |
541 | * @abstract |
542 | * The object at index 0 in the ordered set if there is one, |
543 | * otherwise <code>NULL</code>. |
544 | * |
545 | * @discussion |
546 | * The returned object will be released if removed from the ordered set; |
547 | * if you plan to store the reference, you should call |
548 | * <code>@link |
549 | * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/() |
550 | * retain@/link</code> |
551 | * on that object. |
552 | */ |
553 | virtual OSObject * getFirstObject() const; |
554 | |
555 | |
556 | /*! |
557 | * @function getLastObject |
558 | * |
559 | * @abstract |
560 | * The last object in the ordered set if there is one, |
561 | * otherwise <code>NULL</code>. |
562 | * |
563 | * @discussion |
564 | * The returned object will be released if removed from the ordered set; |
565 | * if you plan to store the reference, you should call |
566 | * <code>@link |
567 | * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/() |
568 | * retain@/link</code> |
569 | * on that object. |
570 | */ |
571 | virtual OSObject * getLastObject() const; |
572 | |
573 | |
574 | /*! |
575 | * @function orderObject |
576 | * |
577 | * @abstract |
578 | * Calls the ordered set's order function against a <code>NULL</code> object. |
579 | * |
580 | * @param anObject The object to be ordered. |
581 | * |
582 | * @result |
583 | * The ordering value for the object. |
584 | * |
585 | * @discussion |
586 | * This function calls the ordered set's |
587 | * @link OSOrderFunction order function@/link |
588 | * with <code>anObject</code>, <code>NULL</code>, and the ordering context |
589 | * (or <code>NULL</code> if none was set), |
590 | * and returns the result of that function. |
591 | */ |
592 | virtual SInt32 orderObject(const OSMetaClassBase * anObject); |
593 | |
594 | |
595 | /*! |
596 | * @function setObject |
597 | * |
598 | * @abstract |
599 | * Adds an object to an OSOrderedSet at a specified index |
600 | * if it is not already present. |
601 | * |
602 | * @param index The index at which to insert the new object. |
603 | * @param anObject The OSMetaClassBase-derived object to be added |
604 | * to the ordered set. |
605 | * |
606 | * @result |
607 | * <code>true</code> if the object was successfully added |
608 | * to the ordered set, <code>false</code> otherwise |
609 | * (including if it was already in the set). |
610 | * |
611 | * @discussion |
612 | * The set adds storage to accomodate the new object, if necessary. |
613 | * If successfully added, the object is retained. |
614 | * |
615 | * This function ignores any ordering function of the ordered set, |
616 | * and can disrupt the automatic sorting mechanism. |
617 | * Only call this function if you are managing the ordered set directly. |
618 | * |
619 | * A <code>false</code> return value can mean either that the object |
620 | * is already present in the set, |
621 | * or that a memory allocation failure occurred. |
622 | * If you need to know whether the object |
623 | * is already present, use |
624 | * <code>@link //apple_ref/cpp/instm/OSOrderedSet/containsObject/virtualbool/(constOSMetaClassBase*) |
625 | * containsObject containsObject@/link</code>. |
626 | */ |
627 | virtual bool setObject( |
628 | unsigned int index, |
629 | const OSMetaClassBase * anObject); |
630 | |
631 | |
632 | /*! |
633 | * @function getObject |
634 | * |
635 | * @abstract |
636 | * Gets the object at a particular index. |
637 | * |
638 | * @param index The index into the set. |
639 | * @result |
640 | * The object at the given index, |
641 | * or <code>NULL</code> if none exists at that location. |
642 | * |
643 | * @discussion |
644 | * The returned object will be released if removed from the set; |
645 | * if you plan to store the reference, you should call |
646 | * <code>@link |
647 | * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/() |
648 | * retain@/link</code> |
649 | * on that object. |
650 | */ |
651 | virtual OSObject * getObject(unsigned int index) const; |
652 | |
653 | |
654 | /*! |
655 | * @function getOrderingRef |
656 | * |
657 | * @abstract |
658 | * Returns the ordering context the ordered set was created with. |
659 | * |
660 | * @result |
661 | * The ordered set's ordering context, |
662 | * or <code>NULL</code> if it doesn't have one. |
663 | */ |
664 | virtual void * getOrderingRef(); |
665 | |
666 | |
667 | /*! |
668 | * @function isEqualTo |
669 | * |
670 | * @abstract |
671 | * Tests the equality of two OSOrderedSet objects. |
672 | * |
673 | * @param anOrderedSet The ordered set object being compared |
674 | * against the receiver. |
675 | * @result |
676 | * <code>true</code> if the two sets are equivalent, |
677 | * <code>false</code> otherwise. |
678 | * |
679 | * @discussion |
680 | * Two OSOrderedSet objects are considered equal if they have same count |
681 | * and the same object pointer values in the same order. |
682 | */ |
683 | virtual bool isEqualTo(const OSOrderedSet * anOrderedSet) const; |
684 | |
685 | |
686 | /*! |
687 | * @function isEqualTo |
688 | * |
689 | * @abstract |
690 | * Tests the equality of an OSOrderedSet |
691 | * against an arbitrary object. |
692 | * |
693 | * @param anObject The object being compared against the receiver. |
694 | * @result |
695 | * <code>true</code> if the two objects are equivalent, |
696 | * <code>false</code> otherwise. |
697 | * |
698 | * @discussion |
699 | * An OSOrderedSet object is considered equal to another object |
700 | * if the other object is derived from OSOrderedSet |
701 | * and compares equal as an OSOrderedSet. |
702 | */ |
703 | virtual bool isEqualTo(const OSMetaClassBase * anObject) const APPLE_KEXT_OVERRIDE; |
704 | |
705 | |
706 | /*! |
707 | * @function setOptions |
708 | * |
709 | * Recursively sets option bits in the ordered set |
710 | * and all child collections. |
711 | * |
712 | * @param options A bitfield whose values turn the options on (1) or off (0). |
713 | * @param mask A mask indicating which bits |
714 | * in <code>options</code> to change. |
715 | * Pass 0 to get the whole current options bitfield |
716 | * without changing any settings. |
717 | * @param context Unused. |
718 | * |
719 | * @result |
720 | * The options bitfield as it was before the set operation. |
721 | * |
722 | * @discussion |
723 | * Kernel extensions should not call this function. |
724 | * |
725 | * Child collections' options are changed only if the receiving ordered set's |
726 | * options actually change. |
727 | */ |
728 | virtual unsigned setOptions( |
729 | unsigned options, |
730 | unsigned mask, |
731 | void * context = 0) APPLE_KEXT_OVERRIDE; |
732 | |
733 | |
734 | /*! |
735 | * @function copyCollection |
736 | * |
737 | * @abstract |
738 | * Creates a deep copy of this ordered set and its child collections. |
739 | * |
740 | * @param cycleDict A dictionary of all of the collections |
741 | * that have been copied so far, |
742 | * which is used to track circular references. |
743 | * To start the copy at the top level, |
744 | * pass <code>NULL</code>. |
745 | * |
746 | * @result |
747 | * The newly copied ordered set, with a retain count of 1, |
748 | * or <code>NULL</code> if there is insufficient memory to do the copy. |
749 | * |
750 | * @discussion |
751 | * The receiving ordered set, and any collections it contains, |
752 | * recursively, are copied. |
753 | * Objects that are not derived from OSCollection are retained |
754 | * rather than copied. |
755 | */ |
756 | OSCollection *copyCollection(OSDictionary * cycleDict = 0) APPLE_KEXT_OVERRIDE; |
757 | |
758 | OSMetaClassDeclareReservedUnused(OSOrderedSet, 0); |
759 | OSMetaClassDeclareReservedUnused(OSOrderedSet, 1); |
760 | OSMetaClassDeclareReservedUnused(OSOrderedSet, 2); |
761 | OSMetaClassDeclareReservedUnused(OSOrderedSet, 3); |
762 | OSMetaClassDeclareReservedUnused(OSOrderedSet, 4); |
763 | OSMetaClassDeclareReservedUnused(OSOrderedSet, 5); |
764 | OSMetaClassDeclareReservedUnused(OSOrderedSet, 6); |
765 | OSMetaClassDeclareReservedUnused(OSOrderedSet, 7); |
766 | }; |
767 | |
768 | #endif /* ! _OS_OSORDEREDSET_H */ |
769 | |