Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add developer documentation forbidding default parameters in detail APIs #12978

Merged
merged 8 commits into from
Mar 22, 2023
Merged

Add developer documentation forbidding default parameters in detail APIs #12978

Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
6717941
Fix typo
vyasr Mar 20, 2023
bf3c75d
Move NVTX ranges to separate section instead of streams subsection.
vyasr Mar 20, 2023
2186557
Add section on default parameters.
vyasr Mar 20, 2023
993c975
Document that all detail APIs allocating memory should accept an mr.
vyasr Mar 21, 2023
cfebb6a
reflow
vyasr Mar 21, 2023
a73e722
Address PR review
vyasr Mar 21, 2023
30280fd
Merge branch 'branch-23.04' into doc/default_detail_params
bdice Mar 21, 2023
1664fbd
Fix typo
vyasr Mar 21, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 25 additions & 9 deletions cpp/doxygen/developer_guide/DEVELOPER_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -475,14 +475,6 @@ asynchrony if and when we add an asynchronous API to libcudf.
**Note:** `cudaDeviceSynchronize()` should *never* be used.
This limits the ability to do any multi-stream/multi-threaded work with libcudf APIs.

### NVTX Ranges

In order to aid in performance optimization and debugging, all compute intensive libcudf functions
should have a corresponding NVTX range. In libcudf, we have a convenience macro `CUDF_FUNC_RANGE()`
that will automatically annotate the lifetime of the enclosing function and use the function's name
as the name of the NVTX range. For more information about NVTX, see
[here](https://github.com/NVIDIA/NVTX/tree/dev/c).

### Stream Creation

There may be times in implementing libcudf features where it would be advantageous to use streams
Expand Down Expand Up @@ -535,7 +527,7 @@ rmm::device_buffer some_function(
### Memory Management

libcudf code generally eschews raw pointers and direct memory allocation. Use RMM classes built to
use `device_memory_resource`(*)s for device memory allocation with automated lifetime management.
use `device_memory_resource`s for device memory allocation with automated lifetime management.

#### rmm::device_buffer
Allocates a specified number of bytes of untyped, uninitialized device memory using a
Expand Down Expand Up @@ -617,6 +609,30 @@ rmm::mr::device_memory_resource * mr = new my_custom_resource{...};
rmm::device_uvector<int32_t> v2{100, s, mr};
```

## Default Parameters

While public libcudf APIs are free to include default function parameters, detail functions should not.
Default memory resource parameters make it easy for developers to accidentally allocate memory using the incorrect resource.
Avoiding default memory resources forces developers to consider each memory allocation carefully.

While streams are not currently exposed in libcudf's API, we plan to do so eventually.
As a result, the same arguments for memory resources also apply to streams.
vyasr marked this conversation as resolved.
Show resolved Hide resolved
Public APIs will default to using `cudf::get_default_stream()`.
vyasr marked this conversation as resolved.
Show resolved Hide resolved
However, including the same default in detail APIs opens the door for developers to forget to pass in a user-provided stream if one is passed to a public API.
Forcing every API to explicitly pass the stream is intended to prevent such mistakes.
vyasr marked this conversation as resolved.
Show resolved Hide resolved

The memory resources -- and eventually, the stream -- are the final parameters for essentially all public APIs.
vyasr marked this conversation as resolved.
Show resolved Hide resolved
For API consistency, the same is true throughout libcudf's internals.
Therefore, a consequence of not allowing default streams or mrs is that no parameters in detail APIs may have defaults.
vyasr marked this conversation as resolved.
Show resolved Hide resolved
vyasr marked this conversation as resolved.
Show resolved Hide resolved

## NVTX Ranges

In order to aid in performance optimization and debugging, all compute intensive libcudf functions
should have a corresponding NVTX range. In libcudf, we have a convenience macro `CUDF_FUNC_RANGE()`
that will automatically annotate the lifetime of the enclosing function and use the function's name
vyasr marked this conversation as resolved.
Show resolved Hide resolved
as the name of the NVTX range. For more information about NVTX, see
[here](https://github.com/NVIDIA/NVTX/tree/dev/c).

## Input/Output Style

The preferred style for how inputs are passed in and outputs are returned is the following:
Expand Down