Merge pull request #11439 from Ivorforce/core-types-refresher

Refresh core_types.rst to remove outdated and redundant information.

Author: mhilbrunner

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 <https://github.com/godotengine/godot/blob/master/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 <doc_gdscript_packed_arrays>` 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 <https://github.com/godotengine/godot/blob/master/core/os/memory.h>`__
 
@@ -231,6 +150,12 @@ scripting API.
 .. |typed_dictionary| replace:: `TypedDictionary <https://github.com/godotengine/godot/blob/master/core/variant/typed_dictionary.h>`__
 .. |pair| replace:: `Pair <https://github.com/godotengine/godot/blob/master/core/templates/pair.h>`__
 
+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
 ----------