/* * Copyright (c) Meta Platforms, Inc. and affiliates. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #pragma once #include <condition_variable> #include <thread> #include <vector> #include <folly/Function.h> namespace folly { /** * For each function `fn` you add to this object, `fn` will be run in a loop * in its own thread, with the thread sleeping between invocations of `fn` * for the duration returned by `fn`'s previous run. * * To clean up these threads, invoke `stop()`, which will interrupt sleeping * threads. `stop()` will wait for already-running functions to return. * * == Alternatives == * * If you want to multiplex multiple functions on the same thread, you can * either use EventBase with AsyncTimeout objects, or FunctionScheduler for * a slightly simpler API. * * == Thread-safety == * * This type follows the common rule that: * (1) const member functions are safe to call concurrently with const * member functions, but * (2) non-const member functions are not safe to call concurrently with * any member functions. * * == Pitfalls == * * Threads and classes don't mix well in C++, so you have to be very careful * if you want to have ThreadedRepeatingFunctionRunner as a member of your * class. A reasonable pattern looks like this: * * // Your class must be `final` because inheriting from a class with * // threads can cause all sorts of subtle issues: * // - Your base class might start threads that attempt to access derived * // class state **before** that state was constructed. * // - Your base class's destructor will only be able to stop threads * // **after** the derived class state was destroyed -- and that state * // might be accessed by the threads. * // In short, any derived class would have to do work to manage the * // threads itself, which makes inheritance a poor means of composition. * struct MyClass final { * // Note that threads are NOT added in the constructor, for two reasons: * // * // (1) If you first added some threads, and then had additional * // initialization (e.g. derived class constructors), `this` might * // not be fully constructed by the time the function threads * // started running, causing heisenbugs. * // * // (2) If your constructor threw after thread creation, the class * // destructor would not be invoked, potentially leaving the * // threads running too long. * // * // It is much safer to have explicit two-step initialization, or to * // lazily add threads the first time they are needed. * MyClass() : count_(0) {} * * // You must stop the threads as early as possible in the destruction * // process (or even before). If MyClass had derived classes, the final * // derived class MUST always call stop() as the first thing in its * // destructor -- otherwise, the worker threads might access already- * // destroyed state. * ~MyClass() { * threads_.stop(); // Stop threads BEFORE destroying any state they use. * } * * // See the constructor for why two-stage initialization is preferred. * void init() { * threads_.add(bind(&MyClass::incrementCount, this)); * } * * std::chrono::milliseconds incrementCount() { * ++count_; * return 10; * } * * private: * std::atomic<int> count_; * // CAUTION: Declare last since the threads access other members of `this`. * ThreadedRepeatingFunctionRunner threads_; * }; */ class ThreadedRepeatingFunctionRunner final { … }; } // namespace folly
Codebase Browser
folly