Consider this:
1 2 3 4 5 | // this is not a type template<typename C> struct buffer { // every instance of template shares this value static inline mutable size_t count = 1024U ; }; |
If we create few template definitions we get the same number of distinctive types, like so:
1 2 3 4 | // 3 concrete types using c_buffer = buffer<char>; using w_buffer = buffer<wchar>; using n_buffer = buffer<int> ; |
So far so good. But. count is shared. It is the same for everyone. All concrete types defined from the same template and all the instances of those types.
1 2 | // true bool the_same_value = c_buffer::count == w_buffer::count == n_buffer::count ; |
Since the count is shared on the type level (aka static user-defined type, member) one change applies to every other type.
1 2 3 | w_buffer::count = 13; //true bool all_are_13 = 13 == c_buffer::count == w_buffer::count == n_buffer::count ; |
This is not so good unless it is a design requirement.
The context
The other day I have developed a handy little template to hold and provide, a plain 2d array on the stack (aka the “matrix”). It is also fully “compile time capable” with the full static internal presentation. Very handy to enforce (gently) company-wide policies of static matrices in standard C++, and to give in the same time some useful functionality in return. I am calling this template “almost a pod”.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 | /* Static matrix_type , almost a pod. All static all stack. */ template < typename T, size_t R, size_t C, size_t MAXSIZE = 0xFFFF /*INT_MAX as a absolute max is 0x7FFFFFFF -- limits.h*/ > class compile_time_stack_matrix final { public: // this is like a 'this' for static template instances // without it code bellow will be more complex using type = compile_time_stack_matrix; // we also clean const and volatile if used "by accident" using value_type = std::remove_cv_t<T>; using matrix_type = value_type[R][C]; using matrix_ref_type = value_type(&)[R][C]; private: /* here we enforce usage policies first The 64-bit PECOFF executable format used on Windows doesn't support creating executables that have a load size of greater than 2GB Since this is all on stack we have choosen here much smaller MAXSIZE then INT_MAX which is 0x7FFFFFFF -- limits.h and thus enfored a stack matrix size policy here */ static_assert( (R * C * sizeof(value_type)) <= MAXSIZE, "Total size of compile_time_stack_matrix must not exceed 0xFFFF (65536) bytes" ); static_assert( std::is_pod_v<value_type>, "compile_time_stack_matrix can be made out of POD types only" ); // just a pod 2D array on stack // this is static and thus shared among all the same // types and all instances of those types inline static value_type data_[R][C]{}; public: static constexpr const char * type_name() { return typeid(matrix_type).name(); } static constexpr size_t rows() noexcept { return R; }; static constexpr size_t cols() noexcept { return C; }; static constexpr size_t size() noexcept { return sizeof(matrix_type); // same as: R * C * sizeof(value_type); // same as sizeof(value_type[R][C]) }; static constexpr size_t rank() noexcept { return std::rank_v < matrix_type >; } static constexpr size_t max_size() noexcept { return MAXSIZE; }; constexpr explicit compile_time_stack_matrix() { static_assert(2 == std::rank_v < matrix_type >); static_assert(R == std::extent_v< matrix_type, 0 >); static_assert(C == std::extent_v< matrix_type, 1 >); } ~compile_time_stack_matrix() { } // Not returning pointer but reference constexpr static matrix_ref_type data() noexcept { return matrix_ref_type(type::data_); } // return type is a reference so we can both // set and get values in the matrix cells easily constexpr static value_type & data (int r, int c) noexcept { return (value_type &)(type::data_[r][c]); } // callback signature has to be // bool (*fun)( value_type & val, size_t row, size_t col); using callback = void (*)( value_type & , size_t , size_t ); // if callback returns false, process stops // if callback throws the exception, process stops template<typename F> constexpr static void for_each(const F & fun) { for (size_t row_ = 0; row_ < R; row_++) { for (size_t col_ = 0; col_ < C; col_++) { if ( false == fun( (value_type &)type::data_[row_][col_], row_, col_ )) return ; } } } // matrix pretty print // F has to be a variadic print function // lambda example of a such function // inline auto print = [](const auto & first_param, auto && ... params); template<typename F> constexpr static void printarr(F print) { print("\n", type::type_name()); for (int r = 0; r < R; r++) { print("\n[ "); for (int c = 0; c < C; c++) print(" [", type::data_[r][c], "] "); print(" ]"); } print("\n"); } }; |
Why this template?
In standard C++ community 2d array’s are the source of endless debate. Especially the large ones created on the heap. But. 90% of use cases require, a plain old 2d array :
// a pod example
int matrix[3][3];
As visible in the code above standard C++ is giving us quite a few mechanisms and features to encapsulate the rules of using such matrices. Usage samples:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | constexpr size_t R = 3; constexpr size_t C = 3; // dbj static matrix solution using mx9 = compile_time_stack_matrix<int, R, C>; // returns ref to internal matrix mx9::matrix_ref_type mx = mx9::data(); // can update this way mx[1][1] = 1; // or can update this way mx9::value_type & val = mx9::data(1, 1); val = 1; // or this way size_t count_(0); mx9::for_each( [&count_](mx9::value_type & val, size_t r, size_t c ) ->bool { val = count_++ ; noexcept(r,c); //dummy usage to pacify msvc return true; // proceed } ); mx9::printarr( dbj::console::print ); |
Not a single instance in sight. All is in the type. Because implementation is keeping it all as one static simple 2d array class member.
Are we done here, then?
No. We are not done here yet. Since everything is static inside this type (aka template definition) it is shared, between all instances of the same type. Actually, there are no instances required. We can make and use them instances, just to show the issue:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | // the unique type using mx9 = compile_time_stack_matrix<int, R, C>; // two instance of the same type // made on the heap, just for fun mx9 * mt1 = new mx9; mx9 * mt2 = new mx9; // change the cell [1][1] on the type mx9::matrix_ref_type mx = mx9::data(); // give it value 1 mx[1][1] = 1; // print all three of them mx9::printarr( dbj::console::print ); mt1->printarr( dbj::console::print ); mt2->printarr( dbj::console::print ); // they are all the same |
We are getting 3 identical matrix outputs. This is because there is no instance bound data inside, it is all shared between all instance of the type mx9 There is a single data member inside and it is static, so-called “class-wide”
// just a pod 2D array on the stack
inline static value_type data_[R][C]{};
Thus each instance of the template definition for the same template arguments T,R,Ccombination will share the same 2d array hidden inside.
In this context, there are no objects (aka instances) just classes, which are in this case template definitions.
How do we differentiate between them?
We have a problem. What are we going to do? We need, for example 3×3 matrices of int’s but we have no instances to keep them separate in the memory.
We could redesign and re-do this template so that nothing is static, true. But this will lead to completely different run-time semantic. And we want, compile time. We want our matrices as fast as possible, as simple as possible, and not made on the (slower) heap. Here is my solution.
Artificially different template definitions
Add template argument, and use it to make them definitions different. Template arguments, on our matrix, are now these:
1 2 3 4 5 6 7 8 9 | template < typename T, size_t R, size_t C, unsigned long UID_, size_t MAXSIZE = 0xFFFF /*INT_MAX as a absolute max is 0x7FFFFFFF -- limits.h*/ > class compile_time_stack_matrix final ; |
There is a new template argument:UID_ Let us assume UID_ is just an ever increasing number. When we create template definitions (aka types), simplified view on what we have now is this:
1 2 3 4 5 6 | // two differnt types, thanks // to the UID template argument using mx9a = compile_time_stack_matrix<int, 3, 3, 1 >; using mx9b = compile_time_stack_matrix<int, 3, 3, 2 >; |
The last template argument effectively creates two distinct types above, which are actually both the same ‘thing’: A static matrix, of size 3×3 with integers in the cells. On the stack, all static. Simple, fast and nothing on the heap.
Here is our all stack all static matrix. Just the changes:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | /* stack static matrix_type almost a pod. */ template < typename T, size_t R, size_t C, unsigned long UID_, size_t MAXSIZE = 0xFFFF > class compile_time_stack_matrix final { public: static constexpr const unsigned long uuid() { return UID_; } }; |
The UID_ argument added. This is what makes it possible.
UID_ has to be a compile time constant. My quick (but not dirty) implementation:
#define DBJ_UID __COUNTER__ + dbj::util::inner::hash(__FILE__)
Where __COUNTER__ is MSVC predefined macro value giving 1,2,3 … on the level of the compilation unit, and the hash function is my constexpr implementation of the famous djb2 hash algorithm.
1 2 3 4 5 6 7 8 9 10 | // dbj stack static matrix solution // two idfferent types // separated by the UID_ value argument using mx9a = compile_time_stack_matrix<int, R, C, DBJ_UID >; using mx9b = compile_time_stack_matrix<int, R, C, DBJ_UID >; // different static_assert(mx9a::uuid() != mx9b::uuid()); |
Actual usage is a bit unusual because instances are not necessary. Just the types. Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | // require matrix as a type // the rest as usual template< typename MX, typename T > void test_mx ( T new_val) { dbj::console::print("\n ID: ", MX::uuid(),", size: ",MX::size(), ", rank: ", MX::rank()); MX::for_each( [&](typename MX::value_type & val, size_t r, size_t c) ->bool { val = new_val++; noexcept(r, c); //dummy usage to pacify msvc return true; // proceed } ); MX::printarr(dbj::console::print); } |
To use the test function declared as above, we pass our matrix as a type and the rest as value:
1 2 3 4 5 6 7 8 9 10 11 12 | constexpr size_t R = 3, C = 3; using mx9a = compile_time_stack_matrix<int, R, C, DBJ_UID >; using mx9b = compile_time_stack_matrix<int, R, C, DBJ_UID >; static_assert( mx9a::uuid() != mx9b::uuid() ); // pass the matrix as a type // as template argument test_mx<mx9a>( 0 ); test_mx<mx9b>( 100 ); |
Above means there is no standard C++, copy or move mechanisms being used whatsoever, The matrix stays in one place, where it was first created.
If one needs, to pass instances of this matrix in and out of function, as values, this is perfectly unnecessary but perfectly doable:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | // note: we receive argument as value // we return the matrix as value // does not matter. There are no instance // bound data inside, compiler has no job // to do copy/move elision and a such // there is nothing to copy or move template< typename MX> MX test_mx_arg_retval(MX the_mx) { // change a cell the_mx.data( the_mx.rows() - 1, the_mx.cols() - 1) = 1234; return the_mx; } |
And the usage:
1 2 3 4 5 | mx9a mxa = test_mx_arg_retval(mx9a()); mx9b mxb = test_mx_arg_retval(mx9b()); mxa.printarr(dbj::console::print); mxb.printarr(dbj::console::print); |
Add that to the last usage example, and you will understand.
We receive argument as value, we return the matrix as value. It does not matter. There is no instance bound data inside, Compiler has no job to do. Copy/move elision is not applicable. There is nothing to copy or move. No instances necessary 🙂
As ever if anybody needs advice on how to use dbj matrix, in her project please do let us know, in the comments below, or through any other modern communication channel available.
