1/*
2 * Copyright (C) 2015-2017 Apple Inc. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 * 1. Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
9 * 2. Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution.
12 *
13 * THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
14 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
18 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
19 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
20 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
21 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
22 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
23 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
24 */
25
26#pragma once
27
28#include <wtf/Ref.h>
29#include <wtf/ThreadSafeRefCounted.h>
30
31namespace WTF {
32
33// SharedTask is a replacement for std::function for cases where:
34//
35// - You'd like to avoid the cost of copying, and would prefer to have reference semantics rather
36// than value semantics.
37// - You want to use FastMalloc rather than system malloc. Note that std::function may avoid malloc
38// entirely in some cases, but that's hard to guarantee.
39// - You intend to share the task with other threads and so want thread-safe reference counting.
40//
41// Here's an example of how SharedTask can be better than std::function. If you do:
42//
43// std::function<int(double)> a = b;
44//
45// Then "a" will get its own copy of all captured by-value variables. The act of copying may
46// require calls to system malloc, and it may be linear time in the total size of captured
47// variables. On the other hand, if you do:
48//
49// RefPtr<SharedTask<int(double)> a = b;
50//
51// Then "a" will point to the same task as b, and the only work involved is the CAS to increase the
52// reference count.
53//
54// Also, SharedTask allows for more flexibility when sharing state between everyone who runs the
55// task. With std::function, you can only share state using by-reference captured variables.
56// SharedTask supports this since, like std::function, it can be built from a lambda (see
57// createSharedTask(), below). But SharedTask also allows you to create your own subclass and put
58// state in member fields. This can be more natural if you want fine-grained control over what
59// state is shared between instances of the task.
60template<typename FunctionType> class SharedTask;
61template<typename PassedResultType, typename... ArgumentTypes>
62class SharedTask<PassedResultType (ArgumentTypes...)> : public ThreadSafeRefCounted<SharedTask<PassedResultType (ArgumentTypes...)>> {
63public:
64 typedef PassedResultType ResultType;
65
66 SharedTask() { }
67 virtual ~SharedTask() { }
68
69 virtual ResultType run(ArgumentTypes...) = 0;
70};
71
72// This is a utility class that allows you to create a SharedTask subclass using a lambda. Usually,
73// you don't want to use this class directly. Use createSharedTask() instead.
74template<typename FunctionType, typename Functor> class SharedTaskFunctor;
75template<typename ResultType, typename... ArgumentTypes, typename Functor>
76class SharedTaskFunctor<ResultType (ArgumentTypes...), Functor> : public SharedTask<ResultType (ArgumentTypes...)> {
77public:
78 SharedTaskFunctor(const Functor& functor)
79 : m_functor(functor)
80 {
81 }
82
83 SharedTaskFunctor(Functor&& functor)
84 : m_functor(WTFMove(functor))
85 {
86 }
87
88private:
89 ResultType run(ArgumentTypes... arguments) override
90 {
91 return m_functor(std::forward<ArgumentTypes>(arguments)...);
92 }
93
94 Functor m_functor;
95};
96
97// Create a SharedTask from a functor, such as a lambda. You can use this like so:
98//
99// RefPtr<SharedTask<void()>> task = createSharedTask<void()>(
100// [=] () {
101// do things;
102// });
103//
104// Note that if you use the [&] capture list, then you're probably doing it wrong. That's because
105// [&] will lead to pointers to the stack (the only exception is if you do something like &x where
106// x is a reference to the heap - but in that case, it's better to use [=, &x] to be explicit). You
107// probably don't want pointers to the stack if you will have tasks running on other threads.
108// Probably the best way to be sure that you're not making a horrible mistake is to always use
109// explicit capture lists. In many cases, [this] is sufficient.
110//
111// On the other hand, if you use something like ParallelHelperClient::runTaskInParallel() (or its
112// helper, runFunctionInParallel(), which does createSharedTask() for you), then it can be OK to
113// use [&], since the stack frame will remain live for the entire duration of the task's lifetime.
114template<typename FunctionType, typename Functor>
115Ref<SharedTask<FunctionType>> createSharedTask(const Functor& functor)
116{
117 return adoptRef(*new SharedTaskFunctor<FunctionType, Functor>(functor));
118}
119template<typename FunctionType, typename Functor>
120Ref<SharedTask<FunctionType>> createSharedTask(Functor&& functor)
121{
122 return adoptRef(*new SharedTaskFunctor<FunctionType, Functor>(WTFMove(functor)));
123}
124
125} // namespace WTF
126
127using WTF::createSharedTask;
128using WTF::SharedTask;
129using WTF::SharedTaskFunctor;
130