Cleanup: Slightly improve virtual array docs

This commit is contained in:
Hans Goudey
2023-12-29 10:51:26 -05:00
parent 6b0ecd9601
commit 8555c22ced

View File

@@ -7,22 +7,22 @@
/** \file
* \ingroup bli
*
* A virtual array is a data structure that behaves similar to an array, but its elements are
* A virtual array is a data structure that behaves similarly to an array, but its elements are
* accessed through virtual methods. This improves the decoupling of a function from its callers,
* because it does not have to know exactly how the data is laid out in memory, or if it is stored
* in memory at all. It could just as well be computed on the fly.
*
* Taking a virtual array as parameter instead of a more specific non-virtual type has some
* tradeoffs. Access to individual elements of the individual elements is higher due to function
* tradeoffs. Access to individual elements of the individual elements is slower due to function
* call overhead. On the other hand, potential callers don't have to convert the data into the
* specific format required for the function. This can be a costly conversion if only few of the
* elements are accessed in the end.
*
* Functions taking a virtual array as input can still optimize for different data layouts. For
* example, they can check if the array is stored as an array internally or if it is the same
* element for all indices. Whether it is worth to optimize for different data layouts in a
* example, they can check if the array references contiguous memory internally or if it is the
* same value for all indices. Whether it is worth optimizing for different data layouts in a
* function has to be decided on a case by case basis. One should always do some benchmarking to
* see of the increased compile time and binary size is worth it.
* see if the increased compile time and binary size is worth it.
*/
#include <optional>
@@ -40,7 +40,7 @@ class GVArray;
class GVMutableArray;
/**
* Is used to quickly check if a varray is a span or single value. This struct also allows
* Used to quickly check if a varray is a span or a single value. This struct also allows
* retrieving multiple pieces of data with a single virtual method call.
*/
struct CommonVArrayInfo {
@@ -57,7 +57,7 @@ struct CommonVArrayInfo {
bool may_have_ownership = true;
/**
* Points either to nothing, a single value or array of values, depending on #type.
* Points either to nothing, a single value, or an array of values, depending on #type.
* If this is a span of a mutable virtual array, it is safe to cast away const.
*/
const void *data;