From de87d5451f09c84b4eb00fdd41ae90db1a8d7464 Mon Sep 17 00:00:00 2001 From: Loic Dachary Date: Tue, 30 Sep 2014 14:10:25 +0200 Subject: [PATCH] common: document C_GatherBuilder and C_Gather * Introduction explaining what they are used for * Commented example to illustrate the abstract description Signed-off-by: Loic Dachary --- src/include/Context.h | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/src/include/Context.h b/src/include/Context.h index 88af79c5d5ce..efc401a267bb 100644 --- a/src/include/Context.h +++ b/src/include/Context.h @@ -351,6 +351,13 @@ public: }; /* + * The C_GatherBuilder remembers each C_Context created by + * C_GatherBuilder.new_sub() in a C_Gather. When a C_Context created + * by new_sub() is complete(), C_Gather forgets about it. When + * C_GatherBuilder notices that there are no C_Context left in + * C_Gather, it calls complete() on the C_Context provided as the + * second argument of the constructor (finisher). + * * How to use C_GatherBuilder: * * 1. Create a C_GatherBuilder on the stack @@ -360,6 +367,15 @@ public: * set one with gather_bld.set_finisher(my_finisher) * 4. Call gather_bld.activate() * + * Example: + * + * C_SaferCond all_done; + * C_GatherBuilder gb(g_ceph_context, all_done); + * j.submit_entry(1, first, 0, gb.new_sub()); // add a C_Context to C_Gather + * j.submit_entry(2, first, 0, gb.new_sub()); // add a C_Context to C_Gather + * gb.activate(); // consume C_Context as soon as they complete() + * all_done.wait(); // all_done is complete() after all new_sub() are complete() + * * The finisher may be called at any point after step 4, including immediately * from the activate() function. * The finisher will never be called before activate(). -- 2.47.3