diff options
Diffstat (limited to 'libbuild2/algorithm.hxx')
| -rw-r--r-- | libbuild2/algorithm.hxx | 85 |
1 files changed, 50 insertions, 35 deletions
diff --git a/libbuild2/algorithm.hxx b/libbuild2/algorithm.hxx index 00d4fdd..439af78 100644 --- a/libbuild2/algorithm.hxx +++ b/libbuild2/algorithm.hxx @@ -331,17 +331,18 @@ namespace build2 } // Match and apply a rule to the action/target with ambiguity detection. - // Increment the target's dependents count, which means that you should call - // this function with the intent to also call execute(). Return the target - // state translating target_state::failed to the failed exception unless - // instructed otherwise. - // - // The try_match() version doesn't issue diagnostics if there is no rule - // match (but fails as match() for all other errors, like rule ambiguity, - // inability to apply, etc). The first half of the result indicated whether - // there was a rule match. - // - // The unmatch argument allows optimizations that avoid calling execute(). + // This is the synchrounous match implementation that waits for completion + // if the target is already being matched. Increment the target's dependents + // count, which means that you should call this function with the intent to + // also call execute*(). Translating target_state::failed to the failed + // exception unless instructed otherwise. + // + // The try_match_sync() version doesn't issue diagnostics if there is no + // rule match (but fails as match_sync() for all other errors, like rule + // ambiguity, inability to apply, etc). The first half of the result + // indicated whether there was a rule match. + // + // The unmatch argument allows optimizations that avoid calling execute*(). // If it is unmatch::unchanged then only unmatch the target if it is known // to be unchanged after match. If it is unmatch::safe, then unmatch the // target if it is safe (this includes unchanged or if we know that someone @@ -351,18 +352,19 @@ namespace build2 enum class unmatch {none, unchanged, safe}; target_state - match (action, const target&, bool fail = true); + match_sync (action, const target&, bool fail = true); pair<bool, target_state> - try_match (action, const target&, bool fail = true); + try_match_sync (action, const target&, bool fail = true); pair<bool, target_state> - match (action, const target&, unmatch); + match_sync (action, const target&, unmatch); // Start asynchronous match. Return target_state::postponed if the - // asynchrounous operation has been started and target_state::busy if the - // target has already been busy. Regardless of the result, match() must be - // called in order to complete the operation (except target_state::failed). + // asynchronous operation has been started and target_state::busy if the + // target has already been busy. Regardless of the result, match_complete() + // must be called in order to complete the operation (except if the result + // is target_state::failed), which has the result semantics of match_sync(). // // If fail is false, then return target_state::failed if the target match // failed. Otherwise, throw the failed exception if keep_going is false and @@ -373,6 +375,12 @@ namespace build2 size_t start_count, atomic_count& task_count, bool fail = true); + target_state + match_complete (action, const target&, bool fail = true); + + pair<bool, target_state> + match_complete (action, const target&, unmatch); + // Apply the specified recipe directly and without incrementing the // dependency counts. The target must be locked. // @@ -400,8 +408,8 @@ namespace build2 void match_inc_dependents (action, const target&); - // Match a rule for the inner operation from withing the outer rule's - // apply() function. See also the companion execute_inner(). + // Match (synchronously) a rule for the inner operation from withing the + // outer rule's apply() function. See also the companion execute_inner(). // target_state match_inner (action, const target&); @@ -514,8 +522,9 @@ namespace build2 resolve_group (action, const target&); // Inject a target as a "prerequisite target" (note: not a prerequisite) of - // another target. Specifically, first match the prerequisite target and - // then add it to the back of the dependent target's prerequisite_targets. + // another target. Specifically, match (synchronously) the prerequisite + // target and then add it to the back of the dependent target's + // prerequisite_targets. // void inject (action, target&, const target& prereq); @@ -542,7 +551,7 @@ namespace build2 // fail is false. // target_state - execute (action, const target&, bool fail = true); + execute_sync (action, const target&, bool fail = true); // As above but start asynchronous execution. Return target_state::unknown // if the asynchrounous execution has been started and target_state::busy if @@ -550,26 +559,32 @@ namespace build2 // // If fail is false, then return target_state::failed if the target // execution failed. Otherwise, throw the failed exception if keep_going is - // false and return target_state::failed otherwise. + // false and return target_state::failed otherwise. Regardless of the + // result, execute_complete() must be called in order to complete the + // operation (except if the result is target_state::failed), which has the + // result semantics of execute_sync(). // target_state execute_async (action, const target&, size_t start_count, atomic_count& task_count, bool fail = true); - // Execute the recipe obtained with match_delegate(). Note that the target's - // state is neither checked nor updated by this function. In other words, - // the appropriate usage is to call this function from another recipe and to - // factor the obtained state into the one returned. + target_state + execute_complete (action, const target&); + + // Execute (synchronously) the recipe obtained with match_delegate(). Note + // that the target's state is neither checked nor updated by this function. + // In other words, the appropriate usage is to call this function from + // another recipe and to factor the obtained state into the one returned. // target_state execute_delegate (const recipe&, action, const target&); - // Execute the inner operation matched with match_inner(). Note that the - // returned target state is for the inner operation. The appropriate usage - // is to call this function from the outer operation's recipe and to factor - // the obtained state into the one returned (similar to how we do it for - // prerequisites). + // Execute (synchronously) the inner operation matched with match_inner(). + // Note that the returned target state is for the inner operation. The + // appropriate usage is to call this function from the outer operation's + // recipe and to factor the obtained state into the one returned (similar to + // how we do it for prerequisites). // // Note: waits for the completion if the target is busy and translates // target_state::failed to the failed exception. @@ -582,11 +597,11 @@ namespace build2 // relationship (so no dependents count is decremented) and execution order // (so this function never returns the postponed target state). // - // Note: the first version waits for the completion if the target is busy - // and translates target_state::failed to the failed exception. + // The first version waits for the completion if the target is busy and + // translates target_state::failed to the failed exception. // target_state - execute_direct (action, const target&); + execute_direct_sync (action, const target&); target_state execute_direct_async (action, const target&, |