1 /* 2 * 3 * Copyright 2019 gRPC authors. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 */ 18 19 #include <grpc/support/port_platform.h> 20 21 #include <functional> 22 23 #include "absl/synchronization/mutex.h" 24 25 #include "src/core/lib/debug/trace.h" 26 #include "src/core/lib/gprpp/atomic.h" 27 #include "src/core/lib/gprpp/debug_location.h" 28 #include "src/core/lib/gprpp/mpscq.h" 29 #include "src/core/lib/gprpp/orphanable.h" 30 #include "src/core/lib/gprpp/ref_counted.h" 31 #include "src/core/lib/iomgr/exec_ctx.h" 32 33 #ifndef GRPC_CORE_LIB_IOMGR_WORK_SERIALIZER_H 34 #define GRPC_CORE_LIB_IOMGR_WORK_SERIALIZER_H 35 36 namespace grpc_core { 37 38 // WorkSerializer is a mechanism to schedule callbacks in a synchronized manner. 39 // All callbacks scheduled on a WorkSerializer instance will be executed 40 // serially in a borrowed thread. The API provides a FIFO guarantee to the 41 // execution of callbacks scheduled on the thread. 42 // When a thread calls Run() with a callback, the thread is considered borrowed. 43 // The callback might run inline, or it might run asynchronously in a different 44 // thread that is already inside of Run(). If the callback runs directly inline, 45 // other callbacks from other threads might also be executed before Run() 46 // returns. Since an arbitrary set of callbacks might be executed when Run() is 47 // called, generally no locks should be held while calling Run(). 48 class ABSL_LOCKABLE WorkSerializer { 49 public: 50 WorkSerializer(); 51 52 ~WorkSerializer(); 53 54 // Runs a given callback. 55 // 56 // If you want to use clang thread annotation to make sure that callback is 57 // called by WorkSerializer only, you need to add the annotation to both the 58 // lambda function given to Run and the actual callback function like; 59 // 60 // void run_callback() { 61 // work_serializer.Run( 62 // []() ABSL_EXCLUSIVE_LOCKS_REQUIRED(work_serializer) { 63 // callback(); 64 // }, DEBUG_LOCATION); 65 // } 66 // void callback() ABSL_EXCLUSIVE_LOCKS_REQUIRED(work_serializer) { ... } 67 // 68 // TODO(yashkt): Replace grpc_core::DebugLocation with absl::SourceLocation 69 // once we can start using it directly. 70 void Run(std::function<void()> callback, 71 const grpc_core::DebugLocation& location); 72 73 private: 74 class WorkSerializerImpl; 75 76 OrphanablePtr<WorkSerializerImpl> impl_; 77 }; 78 79 } /* namespace grpc_core */ 80 81 #endif /* GRPC_CORE_LIB_IOMGR_WORK_SERIALIZER_H */ 82