[FEA] Expose public stream-ordered C++ APIs

[vyasr]

Is your feature request related to a problem? Please describe.
Currently most libcudf APIs operate implicitly on the default CUDA stream. As documented in #925, we would like to expose stream-ordered APIs publicly. Prior to doing so, we needed to do a great deal of work to ensure that libcudf's internals were properly stream-ordered. Among the important tasks here were removing implicit APIs that ran on a stream (see #11968) and implementing a strategy for verifying that streams are properly forwarded from APIs all the way down to the lowest level functions (see #11943). Now that all such work that we are aware of has been completed, libcudf should start exposing streams in public APIs.

We originally considered adding stream support via a monolithic feature branch where APIs would be modified one at a time. From various discussions, however, we decided that the overhead of maintaining a feature branch would grow too large to be worthwhile, so we have instead decided to proceed by incrementally exposing streams in libcudf APIs over time. PRs adding new APIs should always include a stream in the public API. Existing APIs will be transitioned one header file at a time, with PRs going directly into the current main branch of cudf.

The purpose of this PR is to document progress on the task of transitioning existing headers, as well as to describe the process by which new stream-ordered APIs should be added.

Describe the solution you'd like
When adding stream support to an API, the stream parameter should be placed just before the mr parameter with a default value of cudf::get_default_stream(). A new test should be added that validates that the API properly forwards the stream to all CUDA calls, which can be done by following the instructions at the bottom of libcudf's testing developer docs.

To divide up the work, we consider public headers organized by directories (all relative to cpp/include/cudf). Devs may assign themselves a directory within which to own all headers and the public APIs contained therein.

/cudf APIs

• aggregation.hpp
• ast/ Expose stream param in transform APIs #16452
• binaryop.hpp Expose streams in binaryop APIs #14187
• column/
  • column_device_view.hpp
  • column_factories.hpp Replace default stream for scalars and column factories usages (because of defaulted arguments) #14354
  • column_view.hpp Replace default stream for scalars and column factories usages (because of defaulted arguments) #14354
  • column.hpp Replace default stream for scalars and column factories usages (because of defaulted arguments) #14354
• concatenate.hpp Expose streams in public concatenate APIs #13987
• contiguous_split.hpp
• copying.hpp Expose streams in all public copying APIs #13629
• datetime.hpp [FEA] Expose Stream Ordering to the Datetime APIs #16775
• dictionary/
  • dictionary_column_view.hpp
  • dictionary_factories.hpp Add stream parameter to external dict APIs #14115
  • encode.hpp Add stream parameter to external dict APIs #14115
  • search.hpp Add stream parameter to external dict APIs #14115
  • update_keys.h Add stream parameter to external dict APIs #14115
• filling.hpp Expose streams in public filling APIs #13990
• fixed_point/
• groupby.hpp Expose stream-ordering to groupby APIs #17324
• hashing/hashing.hpp Add stream parameter to hashing APIs  #12090
• interop.hpp Expose stream-ordering to interop APIs #17397
• io/
  • csv.hpp Added streams to CSV reader and writer api #14340
  • json.hpp Added streams to JSON reader and writer api #14313
  • parquet.hpp Expose streams in Parquet reader and writer APIs #14359
  • orc.hpp Expose streams in ORC reader and writer APIs #14350
  • avro.hpp Expose streams in the Avro Reader #17631
• join.hpp Exposed stream-ordering to join API #16793
• json/json.hpp
• labeling/label_bins.h Expose streams in public filling APIs for label_bins #14401
• lists/
  • contains.hpp Add stream parameter to List Manipulation and Operations APIs #14248
  • count_elements.hpp Add stream parameter to List Manipulation and Operations APIs #14248
  • count.hpp Add stream parameter to List Manipulation and Operations APIs #14248
  • extract.hpp Add stream parameter to List Sort and Filter APIs #14272
  • gather.hpp Add stream parameter to List Sort and Filter APIs #14272
  • reverse.hpp Add stream parameter to List Sort and Filter APIs #14272
  • sort.hpp Add stream parameter to List Sort and Filter APIs #14272
• merge.hpp cudf::merge public API now support passing a user stream #16124
• null_mask.hpp Expose streams in public null mask APIs #14263
• partitioning.hpp Expose stream-ordering in partitioning API #17213
• quantiles.hpp Expose streams in public quantile APIs #17257
• reduction.hpp
• replace.hpp Expose streams in public replace APIs #14010
• reshape.hpp
• rolling/
• rolling.hpp
• round.hpp Expose streams in public round APIs #16925
• scalar/
  • scalar.hpp Replace default stream for scalars and column factories usages (because of defaulted arguments) #14354
  • scalar_device_view.cuh Replace default stream for scalars and column factories usages (because of defaulted arguments) #14354
  • scalar_factories.hpp Replace default stream for scalars and column factories usages (because of defaulted arguments) #14354
• search.hpp Expose streams in public search APIs #14034
• sorting.hpp Expose streams in all public sorting APIs #14146
• stream_compaction.hpp
• strings/
  • attributes.hpp Expose stream-ordering to strings attribute APIs #17398
  • capitalize.hpp
  • case.hpp Expose streams in public strings case APIs #14056
  • combine.hpp Expose stream parameter in public strings combine APIs #14281
  • contains.hpp Expose stream parameter in public strings contains APIs #14280
  • convert/ Expose stream parameter in public strings convert APIs #14255
  • extract.hpp
  • find.hpp Expose stream parameter in public strings find APIs #14060
  • find_multiple.hpp
  • findall.hpp
  • padding.hpp
  • repeat_strings.hpp
  • replace.hpp Expose stream parameter in public strings replace APIs #14261
  • replace_re.hpp Expose stream parameter in public strings replace APIs #14261
  • reverse.hpp
  • slice.hpp
  • split/ Add stream parameter to public cudf::strings::split APIs #13997 Expose stream parameter in public strings split/partition APIs #14247
  • string_view.cuh
  • string_view.hpp
  • strings_column_view.hpp
  • strip.hpp
  • translate.hpp
  • utilities.hpp
  • wrap.hpp
• structs/
  • struct_view.hpp
  • structs_column_device_view.cuh
  • structs_column_view.hpp
• table/
  • experimental/row_operators.cuh
  • row_operators.cuh
  • table.hpp
  • table_device_view.cuh
  • table_view.hpp
• tdigest/
• timezone.hpp [FEA] Expose Stream Ordering to the Datetime APIs #16775
• transform.hpp
• transpose.hpp Expose stream-ordering in public transpose API #17294
• unary.hpp Expose streams in public unary APIs #14342
• wrappers/

/nvtext APIs

• byte_pair_encoding.hpp
• edit_distance.hpp Expose stream parameter in public nvtext APIs #14456
• generate_ngrams.hpp
• jaccard.hpp
• minhash.hpp
• ngrams_tokenize.hpp Expose stream parameter in public nvtext ngram APIs #14061
• normalize.hpp
• replace.hpp Expose stream parameter in public nvtext replace APIs #14329
• stemmer.hpp
• subword_tokenize.hpp Expose stream-ordering in subword tokenizer API #17206
• tokenize.hpp Expose stream parameter in public nvtext tokenize APIs #14317

Additional context
Before we began making public stream parameters, libcudf public APIs would be paired with detail APIs that are nearly identical except for having a required stream parameter. In some cases, though, the public API may not currently have a detail "mirror" function but instead call multiple detail APIs. In those cases we may need to make a case-by-case determination of whether a new detail function should also be added. Some discussion of whether we want this pattern to be present everywhere, and the reasons why we might want that, are discussed in #14276.

Public stream API readiness:

• revamp the entire test suite to use "test streams"
• create a few multi-stream benchmarks
• create a multi-stream example

[GregoryKimball]

Thanks @lamarrr for reworking this issue!