1// Copyright (c) 2012 The Chromium Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style license that can be 3// found in the LICENSE file. 4 5#ifndef BASE_MAC_LIBDISPATCH_SEQUENCED_TASK_RUNNER_H_ 6#define BASE_MAC_LIBDISPATCH_SEQUENCED_TASK_RUNNER_H_ 7 8#include <dispatch/dispatch.h> 9 10#include "base/single_thread_task_runner.h" 11#include "base/synchronization/waitable_event.h" 12 13namespace base { 14namespace mac { 15 16// This is an implementation of the TaskRunner interface that runs closures on 17// a thread managed by Apple's libdispatch. This has the benefit of being able 18// to PostTask() and friends to a dispatch queue, while being reusable as a 19// dispatch_queue_t. 20// 21// One would use this class if an object lives exclusively on one thread but 22// needs a dispatch_queue_t for use in a system API. This ensures all dispatch 23// callbacks happen on the same thread as Closure tasks. 24// 25// A LibDispatchTaskRunner will continue to run until all references to the 26// underlying dispatch queue are released. 27// 28// Important Notes: 29// - There is no MessageLoop running on this thread, and ::current() returns 30// NULL. 31// - No nested loops can be run, and all tasks are run non-nested. 32// - Work scheduled via libdispatch runs at the same priority as and is 33// interleaved with posted tasks, though FIFO order is guaranteed. 34// 35class BASE_EXPORT LibDispatchTaskRunner : public base::SingleThreadTaskRunner { 36 public: 37 // Starts a new serial dispatch queue with a given name. 38 explicit LibDispatchTaskRunner(const char* name); 39 40 // base::TaskRunner: 41 virtual bool PostDelayedTask(const tracked_objects::Location& from_here, 42 const Closure& task, 43 base::TimeDelta delay) OVERRIDE; 44 virtual bool RunsTasksOnCurrentThread() const OVERRIDE; 45 46 // base::SequencedTaskRunner: 47 virtual bool PostNonNestableDelayedTask( 48 const tracked_objects::Location& from_here, 49 const Closure& task, 50 base::TimeDelta delay) OVERRIDE; 51 52 // This blocks the calling thread until all work on the dispatch queue has 53 // been run and the queue has been destroyed. Destroying a queue requires 54 // ALL retained references to it to be released. Any new tasks posted to 55 // this thread after shutdown are dropped. 56 void Shutdown(); 57 58 // Returns the dispatch queue associated with this task runner, for use with 59 // system APIs that take dispatch queues. The caller is responsible for 60 // retaining the result. 61 // 62 // All properties (context, finalizer, etc.) are managed by this class, and 63 // clients should only use the result of this for dispatch_async(). 64 dispatch_queue_t GetDispatchQueue() const; 65 66 protected: 67 virtual ~LibDispatchTaskRunner(); 68 69 private: 70 static void Finalizer(void* context); 71 72 dispatch_queue_t queue_; 73 74 // The event on which Shutdown waits until Finalizer runs. 75 base::WaitableEvent queue_finalized_; 76}; 77 78} // namespace mac 79} // namespace base 80 81#endif // BASE_MAC_LIBDISPATCH_SEQUENCED_TASK_RUNNER_H_ 82