Feb 18 2019 Array view implementations in Magnum

STL com­pat­ib­il­ity

Con­tinu­ing with how Con­tain­ers::Point­er, Con­tain­ers::Ref­er­en­ce and Con­tain­ers::Op­tion­al re­cently be­came con­vert­ible from/to std::unique_ptr, std::ref­er­en­ce_wrap­per and std::op­tion­al; ar­ray views now ex­pose a sim­il­ar func­tion­al­ity. The Con­tain­ers::Ar­rayView can be im­pli­citly cre­ated from a std::vec­tor or an std::ar­ray ref­er­ence, plus Con­tain­ers::StaticAr­rayView can be im­pli­citly con­ver­ted from the (fixed-size) std::ar­ray. All you need to do is in­clud­ing the Cor­rade/Con­tain­ers/Ar­rayViewStl.h head­er to get the con­ver­sion defin­i­tions. Sim­il­arly as men­tioned in the pre­vi­ous art­icle, it’s a sep­ar­ate head­er to avoid un­con­di­tion­al heavy #include <vector> and #include <array> be­ing trans­it­ively present in all code that touches ar­ray views. With that in place, you can do things like the fol­low­ing — with sli­cing prop­erly bounds-checked, but no fur­ther over­head res­ult­ing from iter­at­or or ele­ment ac­cess:

#include <Corrade/Containers/ArrayViewStl.h>

…

std::vector<float> data;

float sum{}; // Sum of the first 100 elements
for(float i: Containers::arrayView(data).prefix(100))
    sum += i;

In case you’re feel­ing like us­ing the stand­ard C++2a std::span in­stead (or you in­ter­face with a lib­rary us­ing it), there’s no need to worry either. A com­pat­ib­il­ity with it is provided in Cor­rade/Con­tain­ers/Ar­rayViewStlSpan.h. As far as I’m aware, only libc++ ships an im­ple­ment­a­tion of it at the mo­ment. For the span there’s many more dif­fer­ent con­ver­sion pos­sib­il­it­ies, see the docs for more in­form­a­tion. This con­ver­sion is again sep­ar­ate from the rest be­cause (at least the libc++) #include <span> man­aged to gain al­most twice the weight as both #include <vector> and #include <array> to­geth­er. I don’t know how’s that pos­sible for just a fancy pair of point­er and size with a hand­ful of one-liner mem­ber func­tions to be that big, but here we are.

Ar­ray cast­ing

When work­ing with graph­ics data, you of­ten end up with a non-descript “ar­ray of bytes”, com­ing from either some file format or be­ing down­loaded from the GPU. Be­ing able to re­in­ter­pret them as a con­crete type is of­ten very de­sired and Mag­num provides Con­tain­ers::ar­rayCast() for that. Be­sides change of type, it also prop­erly re­cal­cu­lates the size to cor­res­pond to the new type.

Containers::ArrayView<char> data;
auto positions = Containers::arrayCast<Vector3>(data); // array of Vector3

Apart from the con­veni­ence, its main pur­pose is to dir­ect the reinterpret_cast<> ma­chine gun away from your feet. While it can’t fully stop it from fir­ing, it’ll check that both types are stand­ard lay­out (so without vt­ables and oth­er funny busi­ness), that one type has its size a mul­tiple of the oth­er and that the total byte size of the view doesn’t change after the cast. That al­lows you to do fan­ci­er things as well, such as re­in­ter­pret­ing an ar­ray of Mat­rix3 in­to an ar­ray of its column vec­tors:

Containers::ArrayView<Matrix3> poses;
auto baseVectors = Containers::arrayCast<Vector3>(poses);

Note that a cast of the poses to Vec­tor4 would not be per­mit­ted by the checks above. Which is a good thing.

Type eras­ure

Com­ple­ment­ary to the cast­ing func­tion­al­ity, some APIs in Mag­num ac­cept ar­ray views without re­quir­ing any par­tic­u­lar type — vari­ous GPU data up­load func­tions, im­age views and so on. Such APIs care only about the data point­er and byte size. A Con­tain­ers::Ar­rayView<const void> spe­cial­iz­a­tion is used for such case and to make it pos­sible to pass in ar­ray views of any type, it’s im­pli­citly con­vert­ible from them, with their size get­ting re­cal­cu­lated to byte count.

Look­ing at std::span, it provides some­thing sim­il­ar through std::as­_­bytes(), how­ever it’s an ex­pli­cit op­er­a­tion and is us­ing the fancy new std::byte type (which, in my opin­ion, doesn’t add any­thing use­ful over the sim­il­arly opaque void*) — and also, due to that, is not constexpr (while the Mag­num ar­ray view type eras­ure is).

Point­er-like se­mantics

Mag­num’s ar­ray views were de­lib­er­ately chosen to have se­mantics sim­il­ar to C ar­rays — they’re im­pli­citly con­vert­ible to its un­der­ly­ing point­er type (which, again, al­lows us to op­tim­ize de­bug per­form­ance by not hav­ing to ex­pli­citly provide operator[]) and the usu­al point­er arith­met­ic works on them as well. That al­lows them to be more eas­ily used when in­ter­fa­cing with C APIs, for ex­ample like be­low. The std::span doesn’t ex­pose any such func­tion­al­ity.

Containers::ArrayView<const void> data;
std::FILE* file;
std::fwrite(data, 1, data.size(), file);

The point­er-like se­mantics means also that operator== and oth­er com­par­is­on op­er­at­ors work the same way as on point­ers. Ac­cord­ing to cp­pref­er­ence at least, std::span doesn’t provide any of these and since it doesn’t re­tain any­thing else from the point­er-like se­mantics, it’s prob­ably for the bet­ter — since std::span has neither really a point­er nor a con­tain­er se­mantics, both reas­ons for == be­ha­vi­or like on a point­er or like on a con­tain­er are equally val­id for either party and equally con­fus­ing for the oth­er.

Sized null views

While this seemed like an ugly wart at first, I have to ad­mit the whole API be­came more con­sist­ent with such fea­ture in place. It’s about the pos­sib­il­ity to have a view on a nullptr, but with a non-zero size at­tached. This se­mantics is used, among oth­er things, by a few OpenGL APIs, where passing a null point­er to­geth­er with a size will cause a buf­fer or tex­ture to be al­loc­ated but with con­tents un­ini­tial­ized. To do this, it seemed more nat­ur­al to al­low sized ar­ray views be cre­ated from nullptr than to add ded­ic­ated APIs for preal­loc­a­tion. The fol­low­ing will preal­loc­ate a GPU buf­fer to 384 bytes:

GL::Buffer buffer;
buffer.setData({nullptr, 32*3*sizeof(float)});

Later, when adding Con­tain­ers::StaticAr­rayView, this fea­ture al­lowed me to provide it with an im­pli­cit con­struct­or. When check­ing out std::span, I dis­covered that im­pli­cit con­struct­or of the fixed-size vari­ant is not pos­sible.

Containers::StaticArrayView<16, float> a;   // {nullptr, 16}
//std::span<float, 16> b;                   // doesn't compile :(

Com­pile times

To get some real tim­ing, I com­posed a tiny “mi­crobench­mark” shown be­low, with equi­val­ent vari­ants for STL span, GSL span and span lite, us­ing both GCC 8.2 in C++11 mode and Clang 7.0 with libc++ in C++2a mode. Like in the pre­vi­ous art­icle, to bal­ance the com­par­is­on, I’m switch­ing to the stand­ard as­ser­tions by de­fin­ing COR­RADE_STAND­AR­D_ASSERT and, for bet­ter sense of scale, there’s also a baseline time, which is from com­pil­ing just int main() {} with no #include at all.

#include <Corrade/Containers/ArrayView.h>

using namespace Corrade;

int main() {
    int data[]{1, 3, 42, 1337};

    auto a = Containers::arrayView(data);
    Containers::StaticArrayView<1, int> b = a.slice<1>(2);
    return b[0] - 42;
}

g++ main.cpp -DCORRADE_STANDARD_ASSERT -std=c++11                    # either
clang++ main.cpp -DCORRADE_STANDARD_ASSERT -std=c++2a -stdlib=libc++ # or

De­bug per­form­ance

Look­ing at the size of as­sembly out­put for an un­op­tim­ized ver­sion of the snip­pet above, the Mag­num im­ple­ment­a­tion is 1/3 smal­ler than equi­val­ent code writ­ten with Span Lite and about three times smal­ler than the same us­ing GSL span. In all cases the com­piler is able to op­tim­ize everything away at -O1. Un­for­tu­nately Com­piler Ex­plorer doesn’t have an op­tion to use libc++, so couldn’t make a com­par­is­on with std::span there.

Hot take: im­pli­cit all-catch­ing con­struct­ors are stu­pid

I dis­covered the first is­sue when writ­ing the STL com­pat­ib­il­ity con­ver­sions. All Mag­num con­tain­ers and math types have a spe­cial con­struct­or and a con­ver­sion op­er­at­or that makes it pos­sible to con­vert a type either ex­pli­citly or — if the type is simple enough, con­ver­sion not costly and there are no risks of caus­ing am­bigu­ous op­er­at­or over­loads — im­pli­citly from and to a third-party type. This way Mag­num sup­ports seam­less us­age its math types with GLM, Bul­let Phys­ics, Vulkan types or, for ex­ample, Dear ImGui.

This works well and causes no prob­lem as long as the third-party type doesn’t have a con­struct­or that ac­cepts any­thing you throw at it. I ran in­to this is­sue two weeks ago with Ei­gen, as both its Array and Matrix classes have such a con­struct­or. But in that case it’s not harm­ful, only an­noy­ing, as the con­ver­sion can no longer be done dir­ectly through an ex­pli­cit con­ver­sion but rather us­ing some con­ver­sion func­tion.

In case of std::span, it’s much worse — there’s an all-catch­ing con­struct­or tak­ing any con­tain­er-like type. It’s a well meant fea­ture, how­ever, it works even in the case of a fixed-size span — and there it gets dan­ger­ous, as shown be­low. And this is not just a cause of an im­ple­ment­a­tion is­sue in libc++, it’s de­signed this way in the stand­ard it­self — of all things (ex­cep­tions, as­serts, com­pile-time er­rors), it chooses the worst — such con­ver­sion is de­clared as un­defined be­ha­vi­or. For­tu­nately, the good people of Twit­ter already re­cog­nized this as a de­fect and are work­ing on a solu­tion. Hope­fully the fix gets in to­geth­er with the span and not tree years later or some­thing.

#include <span>

struct Vec3 { // your usual Vec3 class
    size_t size() const { return 3; }
    float* data() { return _data; }
    const float* data() const { return _data; }

    private: float _data[3]{};
};

int main() {
    Vec3 a;
    std::span<float, 57> b = a; // this compiles?!?!
}

Im­pli­cit con­ver­sion from std::ini­tial­izer­_l­ist is act­ively har­fmul

Some time ago there was a Twit­ter dis­cus­sion where it was sug­ges­ted to add a con­struct­or tak­ing std::ini­tial­izer­_l­ist to an ar­ray view class. I wondered why Mag­num’s Con­tain­ers::Ar­rayView class doesn’t have such an use­ful fea­ture … un­til I re­membered why. Con­sider this in­no­cent-look­ing snip­pet, guess what hap­pens when you ac­cess b[0] later? If you don’t know, try again with -fsanitize=address.

std::span<const std::string> b{{"hello", "there"}};
b[0]; // ?

Thing is, the above-men­tioned all-catch­ing con­struct­or can cap­ture an std::ini­tial­izer­_l­ist as well, how­ever the prob­lem (com­pared to, let’s say, do­ing the same with a std::vec­tor), is that it gets con­struc­ted im­pli­citly — and so it’s very hard to real­ize the ini­tial­izer list ele­ments are already des­troyed after the semi­colon.

In case of Mag­num, rather than hav­ing ar­ray views im­pli­citly con­struct­ible from std::ini­tial­izer­_l­ist, where it makes sense, APIs tak­ing an ar­ray view have also an ini­tial­izer list over­load. It makes the API sur­face lar­ger, but that’s a reas­on­able price to pay for ar­ray views be­ing safer to use.