diff --git a/contributing/development/core_and_modules/core_types.rst b/contributing/development/core_and_modules/core_types.rst index 4d5d15544..bcf7d2d6e 100644 --- a/contributing/development/core_and_modules/core_types.rst +++ b/contributing/development/core_and_modules/core_types.rst @@ -103,7 +103,30 @@ which are equivalent to new, delete, new[] and delete[]. 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 Vector<>. +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. References: ~~~~~~~~~~~ diff --git a/tutorials/scripting/gdscript/gdscript_basics.rst b/tutorials/scripting/gdscript/gdscript_basics.rst index c80c09aca..60fa034df 100644 --- a/tutorials/scripting/gdscript/gdscript_basics.rst +++ b/tutorials/scripting/gdscript/gdscript_basics.rst @@ -890,6 +890,8 @@ native or user class, or enum. Nested array types (like ``Array[Array[int]]``) a The only exception was made for the ``Array`` (``Array[Variant]``) type, for user convenience and compatibility with old code. However, operations on untyped arrays are considered unsafe. +.. _doc_gdscript_packed_arrays: + Packed arrays ^^^^^^^^^^^^^