The Tor Browser: comparison security/sandbox/chromium/base/threading/sequenced_worker

--1:000000000000
+:0a254b2fd1f8
+// 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.
+#ifndef BASE_THREADING_SEQUENCED_WORKER_POOL_H_
+#define BASE_THREADING_SEQUENCED_WORKER_POOL_H_
+#include <cstddef>
+#include <string>
+#include "base/base_export.h"
+#include "base/basictypes.h"
+#include "base/callback_forward.h"
+#include "base/memory/ref_counted.h"
+#include "base/memory/scoped_ptr.h"
+#include "base/task_runner.h"
+namespace tracked_objects {
+class Location;
+}  // namespace tracked_objects
+namespace base {
+class MessageLoopProxy;
+template <class T> class DeleteHelper;
+class SequencedTaskRunner;
+// A worker thread pool that enforces ordering between sets of tasks. It also
+// allows you to specify what should happen to your tasks on shutdown.
+//
+// To enforce ordering, get a unique sequence token from the pool and post all
+// tasks you want to order with the token. All tasks with the same token are
+// guaranteed to execute serially, though not necessarily on the same thread.
+// This means that:
+//
+//   - No two tasks with the same token will run at the same time.
+//
+//   - Given two tasks T1 and T2 with the same token such that T2 will
+//     run after T1, then T2 will start after T1 is destroyed.
+//
+//   - If T2 will run after T1, then all memory changes in T1 and T1's
+//     destruction will be visible to T2.
+//
+// Example:
+//   SequencedWorkerPool::SequenceToken token = pool.GetSequenceToken();
+//   pool.PostSequencedWorkerTask(token, SequencedWorkerPool::SKIP_ON_SHUTDOWN,
+//                                FROM_HERE, base::Bind(...));
+//   pool.PostSequencedWorkerTask(token, SequencedWorkerPool::SKIP_ON_SHUTDOWN,
+//                                FROM_HERE, base::Bind(...));
+//
+// You can make named sequence tokens to make it easier to share a token
+// across different components.
+//
+// You can also post tasks to the pool without ordering using PostWorkerTask.
+// These will be executed in an unspecified order. The order of execution
+// between tasks with different sequence tokens is also unspecified.
+//
+// This class may be leaked on shutdown to facilitate fast shutdown. The
+// expected usage, however, is to call Shutdown(), which correctly accounts
+// for CONTINUE_ON_SHUTDOWN behavior and is required for BLOCK_SHUTDOWN
+// behavior.
+//
+// Implementation note: This does not use a base::WorkerPool since that does
+// not enforce shutdown semantics or allow us to specify how many worker
+// threads to run. For the typical use case of random background work, we don't
+// necessarily want to be super aggressive about creating threads.
+//
+// Note that SequencedWorkerPool is RefCountedThreadSafe (inherited
+// from TaskRunner).
+class BASE_EXPORT SequencedWorkerPool : public TaskRunner {
+public:
+// Defines what should happen to a task posted to the worker pool on
+// shutdown.
+enum WorkerShutdown {
+// Tasks posted with this mode which have not run at shutdown will be
+// deleted rather than run, and any tasks with this mode running at
+// shutdown will be ignored (the worker thread will not be joined).
+//
+// This option provides a nice way to post stuff you don't want blocking
+// shutdown. For example, you might be doing a slow DNS lookup and if it's
+// blocked on the OS, you may not want to stop shutdown, since the result
+// doesn't really matter at that point.
+//
+// However, you need to be very careful what you do in your callback when
+// you use this option. Since the thread will continue to run until the OS
+// terminates the process, the app can be in the process of tearing down
+// when you're running. This means any singletons or global objects you
+// use may suddenly become invalid out from under you. For this reason,
+// it's best to use this only for slow but simple operations like the DNS
+// example.
+CONTINUE_ON_SHUTDOWN,
+// Tasks posted with this mode that have not started executing at
+// shutdown will be deleted rather than executed. However, any tasks that
+// have already begun executing when shutdown is called will be allowed
+// to continue, and will block shutdown until completion.
+//
+// Note: Because Shutdown() may block while these tasks are executing,
+// care must be taken to ensure that they do not block on the thread that
+// called Shutdown(), as this may lead to deadlock.
+SKIP_ON_SHUTDOWN,
+// Tasks posted with this mode will block shutdown until they're
+// executed. Since this can have significant performance implications,
+// use sparingly.
+//
+// Generally, this should be used only for user data, for example, a task
+// writing a preference file.
+//
+// If a task is posted during shutdown, it will not get run since the
+// workers may already be stopped. In this case, the post operation will
+// fail (return false) and the task will be deleted.
+BLOCK_SHUTDOWN,
+};
+// Opaque identifier that defines sequencing of tasks posted to the worker
+// pool.
+class SequenceToken {
+public:
+SequenceToken() : id_(0) {}
+~SequenceToken() {}
+bool Equals(const SequenceToken& other) const {
+return id_ == other.id_;
+}
+// Returns false if current thread is executing an unsequenced task.
+bool IsValid() const {
+return id_ != 0;
+}
+private:
+friend class SequencedWorkerPool;
+explicit SequenceToken(int id) : id_(id) {}
+int id_;
+};
+// Allows tests to perform certain actions.
+class TestingObserver {
+public:
+virtual ~TestingObserver() {}
+virtual void OnHasWork() = 0;
+virtual void WillWaitForShutdown() = 0;
+virtual void OnDestruct() = 0;
+};
+// Gets the SequencedToken of the current thread.
+// If current thread is not a SequencedWorkerPool worker thread or is running
+// an unsequenced task, returns an invalid SequenceToken.
+static SequenceToken GetSequenceTokenForCurrentThread();
+// When constructing a SequencedWorkerPool, there must be a
+// MessageLoop on the current thread unless you plan to deliberately
+// leak it.
+// Pass the maximum number of threads (they will be lazily created as needed)
+// and a prefix for the thread name to aid in debugging.
+SequencedWorkerPool(size_t max_threads,
+const std::string& thread_name_prefix);
+// Like above, but with |observer| for testing.  Does not take
+// ownership of |observer|.
+SequencedWorkerPool(size_t max_threads,
+const std::string& thread_name_prefix,
+TestingObserver* observer);
+// Returns a unique token that can be used to sequence tasks posted to
+// PostSequencedWorkerTask(). Valid tokens are always nonzero.
+SequenceToken GetSequenceToken();
+// Returns the sequence token associated with the given name. Calling this
+// function multiple times with the same string will always produce the
+// same sequence token. If the name has not been used before, a new token
+// will be created.
+SequenceToken GetNamedSequenceToken(const std::string& name);
+// Returns a SequencedTaskRunner wrapper which posts to this
+// SequencedWorkerPool using the given sequence token. Tasks with nonzero
+// delay are posted with SKIP_ON_SHUTDOWN behavior and tasks with zero delay
+// are posted with BLOCK_SHUTDOWN behavior.
+scoped_refptr<SequencedTaskRunner> GetSequencedTaskRunner(
+SequenceToken token);
+// Returns a SequencedTaskRunner wrapper which posts to this
+// SequencedWorkerPool using the given sequence token. Tasks with nonzero
+// delay are posted with SKIP_ON_SHUTDOWN behavior and tasks with zero delay
+// are posted with the given shutdown behavior.
+scoped_refptr<SequencedTaskRunner> GetSequencedTaskRunnerWithShutdownBehavior(
+SequenceToken token,
+WorkerShutdown shutdown_behavior);
+// Returns a TaskRunner wrapper which posts to this SequencedWorkerPool using
+// the given shutdown behavior. Tasks with nonzero delay are posted with
+// SKIP_ON_SHUTDOWN behavior and tasks with zero delay are posted with the
+// given shutdown behavior.
+scoped_refptr<TaskRunner> GetTaskRunnerWithShutdownBehavior(
+WorkerShutdown shutdown_behavior);
+// Posts the given task for execution in the worker pool. Tasks posted with
+// this function will execute in an unspecified order on a background thread.
+// Returns true if the task was posted. If your tasks have ordering
+// requirements, see PostSequencedWorkerTask().
+//
+// This class will attempt to delete tasks that aren't run
+// (non-block-shutdown semantics) but can't guarantee that this happens. If
+// all worker threads are busy running CONTINUE_ON_SHUTDOWN tasks, there
+// will be no workers available to delete these tasks. And there may be
+// tasks with the same sequence token behind those CONTINUE_ON_SHUTDOWN
+// tasks. Deleting those tasks before the previous one has completed could
+// cause nondeterministic crashes because the task could be keeping some
+// objects alive which do work in their destructor, which could voilate the
+// assumptions of the running task.
+//
+// The task will be guaranteed to run to completion before shutdown
+// (BLOCK_SHUTDOWN semantics).
+//
+// Returns true if the task was posted successfully. This may fail during
+// shutdown regardless of the specified ShutdownBehavior.
+bool PostWorkerTask(const tracked_objects::Location& from_here,
+const Closure& task);
+// Same as PostWorkerTask but allows a delay to be specified (although doing
+// so changes the shutdown behavior). The task will be run after the given
+// delay has elapsed.
+//
+// If the delay is nonzero, the task won't be guaranteed to run to completion
+// before shutdown (SKIP_ON_SHUTDOWN semantics) to avoid shutdown hangs.
+// If the delay is zero, this behaves exactly like PostWorkerTask, i.e. the
+// task will be guaranteed to run to completion before shutdown
+// (BLOCK_SHUTDOWN semantics).
+bool PostDelayedWorkerTask(const tracked_objects::Location& from_here,
+const Closure& task,
+TimeDelta delay);
+// Same as PostWorkerTask but allows specification of the shutdown behavior.
+bool PostWorkerTaskWithShutdownBehavior(
+const tracked_objects::Location& from_here,
+const Closure& task,
+WorkerShutdown shutdown_behavior);
+// Like PostWorkerTask above, but provides sequencing semantics. This means
+// that tasks posted with the same sequence token (see GetSequenceToken())
+// are guaranteed to execute in order. This is useful in cases where you're
+// doing operations that may depend on previous ones, like appending to a
+// file.
+//
+// The task will be guaranteed to run to completion before shutdown
+// (BLOCK_SHUTDOWN semantics).
+//
+// Returns true if the task was posted successfully. This may fail during
+// shutdown regardless of the specified ShutdownBehavior.
+bool PostSequencedWorkerTask(SequenceToken sequence_token,
+const tracked_objects::Location& from_here,
+const Closure& task);
+// Like PostSequencedWorkerTask above, but allows you to specify a named
+// token, which saves an extra call to GetNamedSequenceToken.
+bool PostNamedSequencedWorkerTask(const std::string& token_name,
+const tracked_objects::Location& from_here,
+const Closure& task);
+// Same as PostSequencedWorkerTask but allows a delay to be specified
+// (although doing so changes the shutdown behavior). The task will be run
+// after the given delay has elapsed.
+//
+// If the delay is nonzero, the task won't be guaranteed to run to completion
+// before shutdown (SKIP_ON_SHUTDOWN semantics) to avoid shutdown hangs.
+// If the delay is zero, this behaves exactly like PostSequencedWorkerTask,
+// i.e. the task will be guaranteed to run to completion before shutdown
+// (BLOCK_SHUTDOWN semantics).
+bool PostDelayedSequencedWorkerTask(
+SequenceToken sequence_token,
+const tracked_objects::Location& from_here,
+const Closure& task,
+TimeDelta delay);
+// Same as PostSequencedWorkerTask but allows specification of the shutdown
+// behavior.
+bool PostSequencedWorkerTaskWithShutdownBehavior(
+SequenceToken sequence_token,
+const tracked_objects::Location& from_here,
+const Closure& task,
+WorkerShutdown shutdown_behavior);
+// TaskRunner implementation. Forwards to PostDelayedWorkerTask().
+virtual bool PostDelayedTask(const tracked_objects::Location& from_here,
+const Closure& task,
+TimeDelta delay) OVERRIDE;
+virtual bool RunsTasksOnCurrentThread() const OVERRIDE;
+// Returns true if the current thread is processing a task with the given
+// sequence_token.
+bool IsRunningSequenceOnCurrentThread(SequenceToken sequence_token) const;
+// Blocks until all pending tasks are complete. This should only be called in
+// unit tests when you want to validate something that should have happened.
+// This will not flush delayed tasks; delayed tasks get deleted.
+//
+// Note that calling this will not prevent other threads from posting work to
+// the queue while the calling thread is waiting on Flush(). In this case,
+// Flush will return only when there's no more work in the queue. Normally,
+// this doesn't come up since in a test, all the work is being posted from
+// the main thread.
+void FlushForTesting();
+// Spuriously signal that there is work to be done.
+void SignalHasWorkForTesting();
+// Implements the worker pool shutdown. This should be called during app
+// shutdown, and will discard/join with appropriate tasks before returning.
+// After this call, subsequent calls to post tasks will fail.
+//
+// Must be called from the same thread this object was constructed on.
+void Shutdown() { Shutdown(0); }
+// A variant that allows an arbitrary number of new blocking tasks to
+// be posted during shutdown from within tasks that execute during shutdown.
+// Only tasks designated as BLOCKING_SHUTDOWN will be allowed, and only if
+// posted by tasks that are not designated as CONTINUE_ON_SHUTDOWN. Once
+// the limit is reached, subsequent calls to post task fail in all cases.
+//
+// Must be called from the same thread this object was constructed on.
+void Shutdown(int max_new_blocking_tasks_after_shutdown);
+// Check if Shutdown was called for given threading pool. This method is used
+// for aborting time consuming operation to avoid blocking shutdown.
+//
+// Can be called from any thread.
+bool IsShutdownInProgress();
+protected:
+virtual ~SequencedWorkerPool();
+virtual void OnDestruct() const OVERRIDE;
+private:
+friend class RefCountedThreadSafe<SequencedWorkerPool>;
+friend class DeleteHelper<SequencedWorkerPool>;
+class Inner;
+class Worker;
+const scoped_refptr<MessageLoopProxy> constructor_message_loop_;
+// Avoid pulling in too many headers by putting (almost) everything
+// into |inner_|.
+const scoped_ptr<Inner> inner_;
+DISALLOW_COPY_AND_ASSIGN(SequencedWorkerPool);
+};
+}  // namespace base
+#endif  // BASE_THREADING_SEQUENCED_WORKER_POOL_H_

The Tor Browser / file comparison

comparison: security/sandbox/chromium/base/threading/sequenced_worker_pool.h

security/sandbox/chromium/base/threading/sequenced_worker_pool.h