diff --git a/engine_details/architecture/core_types.rst b/engine_details/architecture/core_types.rst index f31d4da67..d1eaf22f2 100644 --- a/engine_details/architecture/core_types.rst +++ b/engine_details/architecture/core_types.rst @@ -9,87 +9,30 @@ and everything is built upon them. This reference will try to list them in order for their better understanding. -Definitions ------------ - -Godot uses the standard C99 datatypes, such as ``uint8_t``, -``uint32_t``, ``int64_t``, etc. which are nowadays supported by every -compiler. Reinventing the wheel for those is not fun, as it makes code -more difficult to read. - -In general, care is not taken to use the most efficient datatype for a -given task unless using large structures or arrays. ``int`` is used -through most of the code unless necessary. This is done because nowadays -every device has at least a 32-bit bus and can do such operations in -one cycle. It makes code more readable too. - -For files or memory sizes, ``size_t`` is used, which is guaranteed to be -64-bit. - -For Unicode characters, CharType instead of wchar_t is used, because -many architectures have 4 bytes long wchar_t, where 2 bytes might be -desired. However, by default, this has not been forced and CharType maps -directly to wchar_t. - -- `core/typedefs.h `__ - -Memory model ------------- - -PC is a wonderful architecture. Computers often have gigabytes of RAM, -terabytes of storage and gigahertz of CPU, and when an application needs -more resources the OS will swap out the inactive ones. Other -architectures (like mobile or consoles) are in general more limited. - -The most common memory model is the heap, where an application will -request a region of memory, and the underlying OS will try to fit it -somewhere and return it. This often works best and is flexible, -but over time and with abuse, this can lead to segmentation. - -Segmentation slowly creates holes that are too small for most common -allocations, so that memory is wasted. There is a lot of literature -about heap and segmentation, so this topic will not be developed -further here. Modern operating systems use paged memory, which helps -mitigate the problem of segmentation but doesn't solve it. - -However, in many studies and tests, it is shown that given enough -memory, if the maximum allocation size is below a given threshold in -proportion to the maximum heap size and proportion of memory intended to -be unused, segmentation will not be a problem over time as it will -remain constant. In other words, leave 10-20% of your memory free -and perform all small allocations and you are fine. - -Godot ensures that all objects that can be allocated dynamically are -small (less than a few kB at most). But what happens if an allocation is -too large (like an image or mesh geometry or large array)? In this case -Godot has the option to use a dynamic memory pool. This memory needs to -be locked to be accessed, and if an allocation runs out of memory, the -pool will be rearranged and compacted on demand. Depending on the need -of the game, the programmer can configure the dynamic memory pool size. - Allocating memory ----------------- -Godot has many tools for tracking memory usage in a game, especially -during debug. Because of this, the regular C and C++ library calls -should not be used. Instead, a few other ones are provided. +Godot has many tricks for ensuring memory safety and tracking memory +usage. Because of this, the regular C and C++ library calls +should not be used. Instead, a few replacements are provided. For C-style allocation, Godot provides a few macros: -.. code-block:: none +.. code-block:: cpp - memalloc() - memrealloc() - memfree() + memalloc(size) + memrealloc(pointer) + memfree(pointer) These are equivalent to the usual ``malloc()``, ``realloc()``, and ``free()`` of the C standard library. For C++-style allocation, special macros are provided: -.. code-block:: none +.. code-block:: cpp - memnew(Class / Class(args)) + memnew(Class) + memnew(Class(args)) memdelete(instance) memnew_arr(Class, amount) @@ -98,33 +41,9 @@ For C++-style allocation, special macros are provided: These are equivalent to ``new``, ``delete``, ``new[]``, and ``delete[]`` respectively. -memnew/memdelete also use a little C++ magic and notify Objects right -after they are created, and right before they are deleted. - -For dynamic memory, use one of Godot's sequence types such as ``Vector<>`` -or ``LocalVector<>``. ``Vector<>`` behaves much like an STL ``std::vector<>``, -but is simpler and uses Copy-On-Write (CoW) semantics. CoW copies of -``Vector<>`` can safely access the same data from different threads, but -several threads cannot access the same ``Vector<>`` instance safely. -It can be safely passed via public API if it has a ``Packed`` alias. - -The ``Packed*Array`` :ref:`types ` are aliases -for specific ``Vector<*>`` types (e.g., ``PackedByteArray``, -``PackedInt32Array``) that are accessible via GDScript. Outside of core, -prefer using the ``Packed*Array`` aliases for functions exposed to scripts, -and ``Vector<>`` for other occasions. - -``LocalVector<>`` is much more like ``std::vector`` than ``Vector<>``. -It is non-CoW, with less overhead. It is intended for internal use where -the benefits of CoW are not needed. Note that neither ``LocalVector<>`` -nor ``Vector<>`` are drop-in replacements for each other. They are two -unrelated types with similar interfaces, both using a buffer as their -storage strategy. - -``List<>`` is another Godot sequence type, using a doubly-linked list as -its storage strategy. Prefer ``Vector<>`` (or ``LocalVector<>``) over -``List<>`` unless you're sure you need it, as cache locality and memory -fragmentation tend to be more important with small collections. +``memnew``/``memdelete`` also use a little C++ magic to automatically call post-init +and pre-release functions. For example, this is used to notify Objects right after +they are created, and right before they are deleted. - `core/os/memory.h `__ @@ -231,6 +150,12 @@ scripting API. .. |typed_dictionary| replace:: `TypedDictionary `__ .. |pair| replace:: `Pair `__ +Thread safety +~~~~~~~~~~~~~ + +None of Godot's containers are thread-safe. When you expect multiple threads to access them, you must use multithread +protections, like ``Mutex`` or ``Semaphore``. + Math types ----------