Support separate accumulator arguments as an optional multi-output fold API #998

Summary

Support separate leading accumulator arguments as an optional alternative to the tuple result argument for multi-output folds.

PR #994 adds tuple-based multi-output folds. The follow-up API should let users write:

void add_and_count(std::atomic<unsigned int>& sum,
                   std::atomic<unsigned int>& count,
                   unsigned int number);

The general parameter order is accumulators, data product access, then resource access:

void fold_op(Result1&, Result2&,
             DataProduct1 const& d1,
             phlex::handle<DataProduct2> d2,
             Resource);

Proposed behavior

• Treat the contiguous leading non-const lvalue-reference parameters as accumulators.
• Treat the first parameter that is not a non-const lvalue reference as the first input argument.
• Preserve the ordering of data product access followed by resource access.
• Keep the tuple-based API from Implement support for multi-output fold #994 supported. Separate accumulator arguments must be an option, not a replacement.
• Map accumulator outputs to output_product_suffixes(...) in declaration order and validate the output suffix count.

Rationale and discussion

Separate accumulator arguments remove the need to unpack a tuple in the fold callable. However, they can make the boundary between accumulator and input arguments less obvious to a reader. Document the deduction rule and discuss diagnostics for unsupported signatures.

Implement this work in a separate PR from #994.

Affected areas

Review these areas when implementing the API:

• phlex/core/registration_api.hpp: callable argument classification and output-count deduction.
• phlex/core/fold_node.hpp: callable invocation with multiple accumulator references.
• phlex/core/detail/accumulator_node.hpp: accumulator storage and output release.
• phlex/core/fold/send.hpp: preserve per-output send behavior where applicable.
• test/fold_test.cpp: coverage for the optional API and compatibility with tuple-based folds.

Acceptance criteria

• A fold can receive multiple separate leading accumulator references.
• Argument classification follows the documented non-const lvalue-reference boundary rule.
• Data product access and resource access remain supported in the stated order.
• Each output maps to its corresponding output suffix, with suffix-count validation.
• Tests verify output values and downstream consumption of each output.
• Existing tuple-based multi-output folds remain supported and tested.
• Documentation explains both forms and the parameter classification rule.

Sources

Requested by @knoepfel.

• PR: Implement support for multi-output fold #994
• API proposal: Implement support for multi-output fold #994 (review)
• Parameter ordering: Implement support for multi-output fold #994 (comment)
• Boundary rule and optional API clarification: Implement support for multi-output fold #994 (comment)
• Issue creation request: Implement support for multi-output fold #994 (comment)