The Labs \ Source Viewer \ SSCLI \ System.Collections \ ICollection

  1. // ==++==
  2. //
  3. //
  4. // Copyright (c) 2006 Microsoft Corporation. All rights reserved.
  5. //
  6. // The use and distribution terms for this software are contained in the file
  7. // named license.txt, which can be found in the root of this distribution.
  8. // By using this software in any fashion, you are agreeing to be bound by the
  9. // terms of this license.
  10. //
  11. // You must not remove this notice, or any other, from this software.
  12. //
  13. //
  14. // ==--==
  15. /*============================================================
  16. **
  17. ** Interface:  ICollection
  18. **
  19. **
  20. ** Purpose: Base interface for all collections.
  21. **
  22. **
  23. ===========================================================*/
  24. namespace System.Collections
  25. {
  26.     using System;
  27.    
  28.     // Base interface for all collections, defining enumerators, size, and
  29.     // synchronization methods.
  30.     [System.Runtime.InteropServices.ComVisible(true)]
  31.     public interface ICollection : IEnumerable
  32.     {
  33.         // Interfaces are not serialable
  34.         // CopyTo copies a collection into an Array, starting at a particular
  35.         // index into the array.
  36.         //
  37.         void CopyTo(Array array, int index);
  38.        
  39.         // Number of items in the collections.
  40.         int Count {
  41.             get;
  42.         }
  43.        
  44.        
  45.         // SyncRoot will return an Object to use for synchronization
  46.         // (thread safety). You can use this object in your code to take a
  47.         // lock on the collection, even if this collection is a wrapper around
  48.         // another collection. The intent is to tunnel through to a real
  49.         // implementation of a collection, and use one of the internal objects
  50.         // found in that code.
  51.         //
  52.         // In the absense of a static Synchronized method on a collection,
  53.         // the expected usage for SyncRoot would look like this:
  54.         //
  55.         // ICollection col = ...
  56.         // lock (col.SyncRoot) {
  57.         // // Some operation on the collection, which is now thread safe.
  58.         // // This may include multiple operations.
  59.         // }
  60.         //
  61.         //
  62.         // The system-provided collections have a static method called
  63.         // Synchronized which will create a thread-safe wrapper around the
  64.         // collection. All access to the collection that you want to be
  65.         // thread-safe should go through that wrapper collection. However, if
  66.         // you need to do multiple calls on that collection (such as retrieving
  67.         // two items, or checking the count then doing something), you should
  68.         // NOT use our thread-safe wrapper since it only takes a lock for the
  69.         // duration of a single method call. Instead, use Monitor.Enter/Exit
  70.         // or your language's equivalent to the C# lock keyword as mentioned
  71.         // above.
  72.         //
  73.         // For collections with no publically available underlying store, the
  74.         // expected implementation is to simply return the this pointer. Note
  75.         // that the this pointer may not be sufficient for collections that
  76.         // wrap other collections; those should return the underlying
  77.         // collection's SyncRoot property.
  78.         object SyncRoot {
  79.             get;
  80.         }
  81.        
  82.         // Is this collection synchronized (i.e., thread-safe)? If you want a
  83.         // thread-safe collection, you can use SyncRoot as an object to
  84.         // synchronize your collection with. If you're using one of the
  85.         // collections in System.Collections, you could call the static
  86.         // Synchronized method to get a thread-safe wrapper around the
  87.         // underlying collection.
  88.         bool IsSynchronized {
  89.             get;
  90.         }
  91.     }
  92. }

Developer Fusion