gfx::Image: Added thread checker.

ui/gfx/image/image.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // An Image wraps an image any flavor, be it platform-native GdkBitmap/NSImage,
 // or a SkBitmap. This also provides easy conversion to other image types
 // through operator overloading. It will cache the converted representations
 // internally to prevent double-conversion.
 //
 // The lifetime of both the initial representation and any converted ones are
 // tied to the lifetime of the Image's internal storage. To allow Images to be
 // cheaply passed around by value, the actual image data is stored in a ref-
 // counted member. When all Images referencing this storage are deleted, the
 // actual representations are deleted, too.
 //
 // Images can be empty, in which case they have no backing representation.
 // Attempting to use an empty Image will result in a crash.
+//
+// Image is *not thread-safe* for reads or writes. In Debug builds, a thread
+// checker will check that Images are not being used across multiple threads. If
+// you need to pass an image from one thread to another, you have two options:
+// 1. Ensure that you are the sole reference holder of the Image (keeping in
+//    mind that if the Image has been copied that the place you copied it from
+//    will hold a reference to it), and call DetachFromThread() just before
+//    passing the Image to another thread.
+// 2. Get the underlying image representation (e.g., ImageSkia) out of the
+//    image, ensure that it is thread-safe (ImageSkia requires special attention
+//    to make it thread-safe), pass that to another thread, then create a new
+//    Image object on the other side.
 
 #ifndef UI_GFX_IMAGE_IMAGE_H_
 #define UI_GFX_IMAGE_IMAGE_H_
 
 #include <stddef.h>
 
 #include <map>
 #include <memory>
 #include <vector>
 
@@ skipping 144 matching lines @@
   // Swaps this image's internal representations with |other|.
   void SwapRepresentations(gfx::Image* other);
 
 #if defined(OS_MACOSX) && !defined(OS_IOS)
   // Set the default representation's color space. This is used for converting
   // to NSImage. This is used to compensate for PNGCodec not writing or reading
   // colorspace ancillary chunks. (sRGB, iCCP).
   void SetSourceColorSpace(CGColorSpaceRef color_space);
 #endif  // defined(OS_MACOSX) && !defined(OS_IOS)
 
+  // Turns off thread checking on this Image (and all Images sharing its backing
+  // store). This should be used to mark code that is not currently thread-safe
+  // and any usage of this method should be considered a bug and accompanied by
+  // a TODO.
+  // TODO(mgiuca): Remove this method after all uses of Image are thread-safe.
+  void DisableThreadChecking();
+
+  // Informs the thread checker that this Image is about to be moved to another
+  // thread. Should only be used when this Image is the sole reference holder of
+  // its backing store.
+  void DetachFromThread();
+
  private:
   // Returns the type of the default representation.
   RepresentationType DefaultRepresentationType() const;
 
   // Returns the ImageRep of the appropriate type or NULL if there is no
   // representation of that type (and must_exist is false).
   internal::ImageRep* GetRepresentation(
       RepresentationType rep_type, bool must_exist) const;
 
   // Stores a representation into the map. A representation of that type must
   // not already be in the map. Returns a pointer to the representation stored
   // inside the map.
   internal::ImageRep* AddRepresentation(
       std::unique_ptr<internal::ImageRep> rep) const;
 
   // Internal class that holds all the representations. This allows the Image to
   // be cheaply copied.
   scoped_refptr<internal::ImageStorage> storage_;
 };
 
 }  // namespace gfx
 
 #endif  // UI_GFX_IMAGE_IMAGE_H_