diff options
author | Yash Tibrewal <yashkt@google.com> | 2018-03-13 12:42:09 -0700 |
---|---|---|
committer | Yash Tibrewal <yashkt@google.com> | 2018-03-13 12:42:09 -0700 |
commit | fc9c0705b3bd39ad32a002beb4d7b584042a7c11 (patch) | |
tree | 14e18d39c050078b5e13e2da1d79d1cde9946a3b /src/core/lib/iomgr/exec_ctx.h | |
parent | 01d117856414c80b6453a472f9a50c5e7bde0a5a (diff) |
Update documentation for ExecCtx
Diffstat (limited to 'src/core/lib/iomgr/exec_ctx.h')
-rw-r--r-- | src/core/lib/iomgr/exec_ctx.h | 21 |
1 files changed, 15 insertions, 6 deletions
diff --git a/src/core/lib/iomgr/exec_ctx.h b/src/core/lib/iomgr/exec_ctx.h index de97164f02..678ca1e5ac 100644 --- a/src/core/lib/iomgr/exec_ctx.h +++ b/src/core/lib/iomgr/exec_ctx.h @@ -54,23 +54,32 @@ grpc_millis grpc_timespec_to_millis_round_up(gpr_timespec timespec); namespace grpc_core { /** Execution context. * A bag of data that collects information along a callstack. - * Generally created at public API entry points, and passed down as - * pointer to child functions that manipulate it. + * It is created on the stack at public API entry points, and stored internally + * as a thread-local variable. + * + * Generally, to create an exec_ctx instance, add the following line at the top + * of the public API entry point or at the start of a thread's work function : + * + * grpc_core::ExecCtx exec_ctx; + * + * Access the created ExecCtx instance using : + * grpc_core::ExecCtx::Get() * * Specific responsibilities (this may grow in the future): * - track a list of work that needs to be delayed until the top of the * call stack (this provides a convenient mechanism to run callbacks * without worrying about locking issues) - * - provide a decision maker (via grpc_exec_ctx_ready_to_finish) that provides + * - provide a decision maker (via IsReadyToFinish) that provides a * signal as to whether a borrowed thread should continue to do work or * should actively try to finish up and get this thread back to its owner * * CONVENTIONS: * - Instance of this must ALWAYS be constructed on the stack, never * heap allocated. - * - Instances and pointers to them must always be called exec_ctx. - * - Instances are always passed as the first argument to a function that - * takes it, and always as a pointer (grpc_exec_ctx is never copied). + * - Exactly one instance of ExecCtx must be created per thread. Instances must + * always be called exec_ctx. + * - Do not pass exec_ctx as a parameter to a function. Always access it using + * grpc_core::ExecCtx::Get() */ class ExecCtx { public: |