From 95fab808c3fb1821bff4881bff9e3dae5d930000 Mon Sep 17 00:00:00 2001 From: Mark Harris Date: Tue, 3 Aug 2021 14:25:47 +1000 Subject: [PATCH 1/2] Add spans and more include guidance --- cpp/docs/DEVELOPER_GUIDE.md | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/cpp/docs/DEVELOPER_GUIDE.md b/cpp/docs/DEVELOPER_GUIDE.md index 9ec64060847..81b566467b5 100644 --- a/cpp/docs/DEVELOPER_GUIDE.md +++ b/cpp/docs/DEVELOPER_GUIDE.md @@ -144,6 +144,16 @@ The following guidelines apply to organizing `#include` lines. * Always check that includes are only necessary for the file in which they are included. Try to avoid excessive including especially in header files. Double check this when you remove code. + * Use quotes `"` to include local headers from the same relative source directory. This should only + occur in source files and non-public header files. Otherwise use angle brackets `<>` around + included header filenames. + * Avoid relative paths with `..` when possible. Paths with `..` are necessary when including + (internal) headers from source paths not in the same directory as the including file, + because source paths are not passed with `-I`. + * Avoid including library internal headers from non-internal files. For example, try not to include + headers from libcudf `src` directories in tests or in libcudf public headers. If you find + yourself doing this, start a discussion about moving (parts of) the included internal header + to a public header. # libcudf Data Structures @@ -246,7 +256,20 @@ An *immutable*, non-owning view of a table. ### `cudf::mutable_table_view` -A *mutable*, non-owning view of a table. +A *mutable*, non-owning view of a table. + +## Spans + +libcudf provides `span` classes that mimic C++20 `std::span`, which is a lightweight +view of a contiguous sequence of objects. libcudf provides two classes, `host_span` and +`device_span`, which can be constructed from multiple container types, or from a pointer +(host or device, respectively) and size, or from iterators. `span` types are useful for defining +generic (internal) interfaces which work with multiple input container types. `device_span` can be +constructed from `thrust::device_vector`, `rmm::device_vector`, or `rmm::device_uvector`. +`host_span` can be constructed from `thrust::host_vector`, `std::vector`, or `std::basic_string`. + +If you are definining internal (detail) functions that operate on vectors, use spans for the input +vector parameters rather than a specific vector type, to make your functions more widely applicable. ## `cudf::scalar` From a4b704c4fe06d6df87942cc7f7ee755c5bc411f5 Mon Sep 17 00:00:00 2001 From: Mark Harris Date: Wed, 11 Aug 2021 10:50:51 +1000 Subject: [PATCH 2/2] Add documentation of `span` --- cpp/docs/DEVELOPER_GUIDE.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/cpp/docs/DEVELOPER_GUIDE.md b/cpp/docs/DEVELOPER_GUIDE.md index 81b566467b5..1da2d43cf6c 100644 --- a/cpp/docs/DEVELOPER_GUIDE.md +++ b/cpp/docs/DEVELOPER_GUIDE.md @@ -271,6 +271,17 @@ constructed from `thrust::device_vector`, `rmm::device_vector`, or `rmm::device_ If you are definining internal (detail) functions that operate on vectors, use spans for the input vector parameters rather than a specific vector type, to make your functions more widely applicable. +When a `span` refers to immutable elements, use `span`, not `span const`. Since a span +is lightweight view, it does not propagate `const`-ness. Therefore, `const` should be applied to +the template type parameter, not to the `span` itself. Also, `span` should be passed by value +because it is a lightweight view. APIS in libcudf that take spans as input will look like the +following function that copies device data to a host `std::vector`. + +```c++ +template +std::vector make_std_vector_async(device_span v, rmm::cuda_stream_view stream) +``` + ## `cudf::scalar` A `cudf::scalar` is an object that can represent a singular, nullable value of any of the types