Add Device::Lock for acquiring devices safely

To aid in acquiring devices in an exception-safe manner, a convenience class
Device::Lock was added that acquires the specified device for the duration of
the object.

2 files changed, 47 insertions, 0 deletions

diff --git a/cairomm/device.cc b/cairomm/device.cc
index f4bff2e..b53f252 100644
--- a/cairomm/device.cc
+++ b/cairomm/device.cc
@@ -79,6 +79,24 @@ void Device::release()
   check_object_status_and_throw_exception(*this);
 }
 
+Device::Lock::Lock(const RefPtr<Device>& device) :
+  m_device(device)
+{
+  m_device->acquire();
+}
+
+Device::Lock::Lock (const Lock& other) :
+  m_device(other.m_device)
+{
+  m_device->acquire();
+}
+
+Device::Lock::~Lock()
+{
+  m_device->release();
+}
+
+
 } //namespace Cairo
 
 // vim: ts=2 sw=2 et
diff --git a/cairomm/device.h b/cairomm/device.h
index 056a693..e2e94d4 100644
--- a/cairomm/device.h
+++ b/cairomm/device.h
@@ -36,6 +36,35 @@ namespace Cairo
 class Device
 {
 public:
+  /** A convenience class for acquiring a Device object in an exception-safe
+   * manner.  The device is automatically acquired when a Lock object is created
+   * and released when the Lock object is destroyed.  For example:
+   *
+   * @code
+   * void
+   * my_device_modifying_function (const RefPtr<Device>& device)
+   * {
+   *   // Ensure the device is properly reset
+   *   device->flush();
+   *
+   *   Device::Lock lock(device);
+   *   // Do the custom operations on the device here.
+   *   // But do not call any Cairo functions that might acquire devices.
+   *
+   * } // device is automatically released at the end of the function scope
+   * @endcode
+   */
+  class Lock
+  {
+  public:
+    /** Create a new Device lock for @a device */
+    Lock (const RefPtr<Device>& device);
+    Lock (const Lock& other);
+    ~Lock();
+
+  private:
+    RefPtr<Device> m_device;
+  };
 
   /** Create a C++ wrapper for the C instance. This C++ instance should then be given to a RefPtr.
    * @param cobject The C instance.