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