Is this a duplicate?
Is this for new documentation, or an update to existing docs?
Update
Describe the incorrect/future/missing documentation
Many CUB histogram APIs have signatures like this:
template <int NUM_CHANNELS,
int NUM_ACTIVE_CHANNELS,
...>
... static cudaError_t MultiHistogramEven(
...,
CounterT* d_histogram[NUM_ACTIVE_CHANNELS],
int num_levels[NUM_ACTIVE_CHANNELS],
LevelT lower_level[NUM_ACTIVE_CHANNELS],
LevelT upper_level[NUM_ACTIVE_CHANNELS],
...)(See: https://github.com/NVIDIA/cccl/blob/main/cub/cub/device/device_histogram.cuh#L597-L613)
Parameters like CounterT* d_histogram[NUM_ACTIVE_CHANNELS] suggest that an array of NUM_ACTIVE_CHANNELS values is expected. However, syntactically, the parameter type is just CounterT** since the array extent is ignored. The API can in fact be called with arrays of more or less than NUM_ACTIVE_CHANNELS values, or with plain pointers. This may be surprising to some users or wrongly encourage them to setup parameters as native arrays, while they could pass arguments of a wider range of types.
A way to enforce the array extent, is to take the array by reference: CounterT* (&d_histogram)[NUM_ACTIVE_CHANNELS]. However, this would break all existing code depending on the current array to pointer decay. I therefore suggest to use plain pointers in the API, which better expresses the current API surface:
template <int NUM_CHANNELS,
int NUM_ACTIVE_CHANNELS,
...>
... static cudaError_t MultiHistogramEven(
...,
CounterT** d_histogram,
int* num_levels,
LevelT* lower_level,
LevelT* upper_level,
...)If this is a correction, please provide a link to the incorrect documentation. If this is a new documentation request, please link to where you have looked.
N/A
Is this a duplicate?
Is this for new documentation, or an update to existing docs?
Update
Describe the incorrect/future/missing documentation
Many CUB histogram APIs have signatures like this:
(See: https://github.com/NVIDIA/cccl/blob/main/cub/cub/device/device_histogram.cuh#L597-L613)
Parameters like
CounterT* d_histogram[NUM_ACTIVE_CHANNELS]suggest that an array ofNUM_ACTIVE_CHANNELSvalues is expected. However, syntactically, the parameter type is justCounterT**since the array extent is ignored. The API can in fact be called with arrays of more or less thanNUM_ACTIVE_CHANNELSvalues, or with plain pointers. This may be surprising to some users or wrongly encourage them to setup parameters as native arrays, while they could pass arguments of a wider range of types.A way to enforce the array extent, is to take the array by reference:
CounterT* (&d_histogram)[NUM_ACTIVE_CHANNELS]. However, this would break all existing code depending on the current array to pointer decay. I therefore suggest to use plain pointers in the API, which better expresses the current API surface:If this is a correction, please provide a link to the incorrect documentation. If this is a new documentation request, please link to where you have looked.
N/A