diff --git a/core/templates/fixed_vector.h b/core/templates/fixed_vector.h new file mode 100644 index 00000000000..37622cd2fa4 --- /dev/null +++ b/core/templates/fixed_vector.h @@ -0,0 +1,163 @@ +/**************************************************************************/ +/* fixed_vector.h */ +/**************************************************************************/ +/* This file is part of: */ +/* GODOT ENGINE */ +/* https://godotengine.org */ +/**************************************************************************/ +/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */ +/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */ +/* */ +/* Permission is hereby granted, free of charge, to any person obtaining */ +/* a copy of this software and associated documentation files (the */ +/* "Software"), to deal in the Software without restriction, including */ +/* without limitation the rights to use, copy, modify, merge, publish, */ +/* distribute, sublicense, and/or sell copies of the Software, and to */ +/* permit persons to whom the Software is furnished to do so, subject to */ +/* the following conditions: */ +/* */ +/* The above copyright notice and this permission notice shall be */ +/* included in all copies or substantial portions of the Software. */ +/* */ +/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */ +/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */ +/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */ +/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */ +/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */ +/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */ +/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/**************************************************************************/ + +#pragma once + +/** + * A high performance Vector of fixed capacity. + * Especially useful if you need to create an array on the stack, to + * prevent dynamic allocations (especially in bottleneck code). + * + * Choose CAPACITY such that it is enough for all elements that could be added through all branches. + * + */ +template +class FixedVector { + // This declaration allows us to access other FixedVector's private members. + template + friend class FixedVector; + + uint32_t _size = 0; + alignas(T) uint8_t _data[CAPACITY * sizeof(T)]; + + constexpr static uint32_t DATA_PADDING = MAX(alignof(T), alignof(uint32_t)) - alignof(uint32_t); + +public: + _FORCE_INLINE_ constexpr FixedVector() = default; + constexpr FixedVector(std::initializer_list p_init) { + ERR_FAIL_COND(p_init.size() > CAPACITY); + for (const T &element : p_init) { + memnew_placement(ptr() + _size++, T(element)); + } + } + + template + constexpr FixedVector(const FixedVector &p_from) { + ERR_FAIL_COND(p_from.size() > CAPACITY); + if constexpr (std::is_trivially_copyable_v) { + // Copy size and all provided elements at once. + memcpy((void *)&_size, (void *)&p_from._size, sizeof(_size) + DATA_PADDING + p_from.size() * sizeof(T)); + } else { + for (const T &element : p_from) { + memnew_placement(ptr() + _size++, T(element)); + } + } + } + + template + constexpr FixedVector(FixedVector &&p_from) { + ERR_FAIL_COND(p_from.size() > CAPACITY); + // Copy size and all provided elements at once. + // Note: Assumes trivial relocatability. + memcpy((void *)&_size, (void *)&p_from._size, sizeof(_size) + DATA_PADDING + p_from.size() * sizeof(T)); + p_from._size = 0; + } + + ~FixedVector() { + if constexpr (!std::is_trivially_destructible_v) { + for (uint32_t i = 0; i < _size; i++) { + ptr()[i].~T(); + } + } + } + + _FORCE_INLINE_ constexpr T *ptr() { return (T *)(_data); } + _FORCE_INLINE_ constexpr const T *ptr() const { return (const T *)(_data); } + + _FORCE_INLINE_ constexpr operator Span() const { return Span(ptr(), size()); } + _FORCE_INLINE_ constexpr Span span() const { return operator Span(); } + + _FORCE_INLINE_ constexpr uint32_t size() const { return _size; } + _FORCE_INLINE_ constexpr bool is_empty() const { return !_size; } + _FORCE_INLINE_ constexpr bool is_full() const { return _size == CAPACITY; } + _FORCE_INLINE_ constexpr uint32_t capacity() const { return CAPACITY; } + + _FORCE_INLINE_ constexpr void clear() { resize_initialized(0); } + + /// Changes the size of the vector. + /// If p_size > size(), constructs new elements. + /// If p_size < size(), destructs new elements. + constexpr Error resize_initialized(uint32_t p_size) { + if (p_size > _size) { + ERR_FAIL_COND_V(p_size > CAPACITY, ERR_OUT_OF_MEMORY); + memnew_arr_placement(ptr() + _size, p_size - _size); + } else if (p_size < _size) { + if constexpr (!std::is_trivially_destructible_v) { + for (uint32_t i = p_size; i < _size; i++) { + ptr()[i].~T(); + } + } + } + + _size = p_size; + return OK; + } + + /// Changes the size of the vector. + /// The initializer of new elements is skipped, making this function faster than resize_initialized. + /// The caller is required to initialize the new values. + constexpr Error resize_uninitialized(uint32_t p_size) { + static_assert(std::is_trivially_destructible_v, "resize_uninitialized is unsafe to call if T is not trivially destructible."); + ERR_FAIL_COND_V(p_size > CAPACITY, ERR_OUT_OF_MEMORY); + _size = p_size; + return OK; + } + + constexpr void push_back(const T &p_val) { + ERR_FAIL_COND(_size >= CAPACITY); + memnew_placement(ptr() + _size, T(p_val)); + _size++; + } + + constexpr void pop_back() { + ERR_FAIL_COND(_size == 0); + _size--; + ptr()[_size].~T(); + } + + // NOTE: Subscripts sanity check the bounds to avoid undefined behavior. + // This is slower than direct buffer access and can prevent autovectorization. + // If the bounds are known, use ptr() subscript instead. + constexpr const T &operator[](uint32_t p_index) const { + CRASH_COND(p_index >= _size); + return ptr()[p_index]; + } + + constexpr T &operator[](uint32_t p_index) { + CRASH_COND(p_index >= _size); + return ptr()[p_index]; + } + + _FORCE_INLINE_ constexpr T *begin() { return ptr(); } + _FORCE_INLINE_ constexpr T *end() { return ptr() + _size; } + + _FORCE_INLINE_ constexpr const T *begin() const { return ptr(); } + _FORCE_INLINE_ constexpr const T *end() const { return ptr() + _size; } +}; diff --git a/tests/core/templates/test_fixed_vector.h b/tests/core/templates/test_fixed_vector.h new file mode 100644 index 00000000000..8ac52617116 --- /dev/null +++ b/tests/core/templates/test_fixed_vector.h @@ -0,0 +1,107 @@ +/**************************************************************************/ +/* test_fixed_vector.h */ +/**************************************************************************/ +/* This file is part of: */ +/* GODOT ENGINE */ +/* https://godotengine.org */ +/**************************************************************************/ +/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */ +/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */ +/* */ +/* Permission is hereby granted, free of charge, to any person obtaining */ +/* a copy of this software and associated documentation files (the */ +/* "Software"), to deal in the Software without restriction, including */ +/* without limitation the rights to use, copy, modify, merge, publish, */ +/* distribute, sublicense, and/or sell copies of the Software, and to */ +/* permit persons to whom the Software is furnished to do so, subject to */ +/* the following conditions: */ +/* */ +/* The above copyright notice and this permission notice shall be */ +/* included in all copies or substantial portions of the Software. */ +/* */ +/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */ +/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */ +/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */ +/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */ +/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */ +/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */ +/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/**************************************************************************/ + +#pragma once + +#include "core/templates/fixed_vector.h" + +#include "tests/test_macros.h" + +namespace TestFixedVector { + +TEST_CASE("[FixedVector] Basic Checks") { + FixedVector vector; + CHECK_EQ(vector.capacity(), 1); + + CHECK_EQ(vector.size(), 0); + CHECK(vector.is_empty()); + CHECK(!vector.is_full()); + + vector.push_back(5); + CHECK_EQ(vector.size(), 1); + CHECK_EQ(vector[0], 5); + CHECK_EQ(vector.ptr()[0], 5); + CHECK(!vector.is_empty()); + CHECK(vector.is_full()); + + vector.pop_back(); + CHECK_EQ(vector.size(), 0); + CHECK(vector.is_empty()); + CHECK(!vector.is_full()); + + FixedVector vector1 = { 1, 2 }; + CHECK_EQ(vector1.capacity(), 2); + CHECK_EQ(vector1.size(), 2); + CHECK_EQ(vector1[0], 1); + CHECK_EQ(vector1[1], 2); + + FixedVector vector2(vector1); + CHECK_EQ(vector2.capacity(), 3); + CHECK_EQ(vector2.size(), 2); + CHECK_EQ(vector2[0], 1); + CHECK_EQ(vector2[1], 2); + + FixedVector vector_variant; + CHECK_EQ(vector_variant.size(), 0); + CHECK_EQ(vector_variant.capacity(), 3); + vector_variant.resize_initialized(3); + vector_variant[0] = "Test"; + vector_variant[1] = 1; + CHECK_EQ(vector_variant.capacity(), 3); + CHECK_EQ(vector_variant.size(), 3); + CHECK_EQ(vector_variant[0], "Test"); + CHECK_EQ(vector_variant[1], Variant(1)); + CHECK_EQ(vector_variant[2].get_type(), Variant::NIL); +} + +TEST_CASE("[FixedVector] Alignment Checks") { + FixedVector vector_uint16; + vector_uint16.resize_uninitialized(4); + CHECK((size_t)&vector_uint16[0] % alignof(uint16_t) == 0); + CHECK((size_t)&vector_uint16[1] % alignof(uint16_t) == 0); + CHECK((size_t)&vector_uint16[2] % alignof(uint16_t) == 0); + CHECK((size_t)&vector_uint16[3] % alignof(uint16_t) == 0); + + FixedVector vector_uint32; + vector_uint32.resize_uninitialized(4); + CHECK((size_t)&vector_uint32[0] % alignof(uint32_t) == 0); + CHECK((size_t)&vector_uint32[1] % alignof(uint32_t) == 0); + CHECK((size_t)&vector_uint32[2] % alignof(uint32_t) == 0); + CHECK((size_t)&vector_uint32[3] % alignof(uint32_t) == 0); + + FixedVector vector_uint64; + vector_uint64.resize_uninitialized(4); + CHECK((size_t)&vector_uint64[0] % alignof(uint64_t) == 0); + CHECK((size_t)&vector_uint64[1] % alignof(uint64_t) == 0); + CHECK((size_t)&vector_uint64[2] % alignof(uint64_t) == 0); + CHECK((size_t)&vector_uint64[3] % alignof(uint64_t) == 0); +} + +} //namespace TestFixedVector diff --git a/tests/test_main.cpp b/tests/test_main.cpp index 7a3efdb5e31..96e2515dd41 100644 --- a/tests/test_main.cpp +++ b/tests/test_main.cpp @@ -95,6 +95,7 @@ #include "tests/core/string/test_translation_server.h" #include "tests/core/templates/test_a_hash_map.h" #include "tests/core/templates/test_command_queue.h" +#include "tests/core/templates/test_fixed_vector.h" #include "tests/core/templates/test_hash_map.h" #include "tests/core/templates/test_hash_set.h" #include "tests/core/templates/test_list.h"