Briefly document Vector<> variations #10382
Conversation
`Packed*Array` aliases seem universally preferred where available, so a link to the list of types seems appropriate. `LocalVector` is used sparingly, so mentioning the intent and rough tradeoff involved seems right for an overview.
|
Please do check my understanding is correct - this is based off my reading of the source, and commentary from #10329, but there may be nuances which I'm missing. |
Co-authored-by: A Thousand Ships <[email protected]>
| @@ -103,7 +103,18 @@ 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 Godot's ``Vector<>`` or one of its variations. | |||
| Godot's ``Vector<>`` behaves much like an STL ``std::vector<>``, but is simpler, | |||
There was a problem hiding this comment.
Vector is not fully thread safe. CoW copies of Vector can safely access the same data from different threads, but several threads cannot access the same Vector instance safely.
|
|
||
| The ``Packed*Array`` :ref:`types <doc_gdscript_packed_arrays>` are aliases for | ||
| specific ``Vector<*>`` types (e.g., ``PackedByteArray``, ``PackedInt32Array``) | ||
| that are accessible via GDScript. Prefer using the ``Packed*Array`` aliases |
There was a problem hiding this comment.
I haven't seen this be done very much in core, is using Packed aliases actually preferred?
There was a problem hiding this comment.
core might be the exception, as the aliases are defined in Variant. Virtually everything outside of core will include Variant by default, so in those instances I've generally seen the aliases used more.
There was a problem hiding this comment.
My personal interpretation is to use Packed*Array for functions exposed to scripts, and Vector<> for other occasions.
| that are accessible via GDScript. Prefer using the ``Packed*Array`` aliases | ||
| when available. | ||
|
|
||
| ``LocalVector<>`` is a non-COW version, with less overhead. It is intended for |
There was a problem hiding this comment.
LocalVector is much more like std::vector than Vector. Maybe it should be covered first, with the intro sentence of comparing to STL std::vector?
| @@ -103,7 +103,18 @@ 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 Godot's ``Vector<>`` or one of its variations. | |||
There was a problem hiding this comment.
LocalVector is not a variation of Vector. Rather, they're two unrelated types with similar interfaces, and both have a buffer as its storage strategy. I'd rather phrase it like "Use one of the sequence types" or something like that. Although List has a very different storage strategy than both Vector and LocalVector, it should probably be mentioned here too (though I would hesitate to recommend to actually use it since it's a linked list).
| For dynamic memory, use Godot's ``Vector<>`` or one of its variations. | ||
| Godot's ``Vector<>`` behaves much like an STL ``std::vector<>``, but is simpler, | ||
| thread safe, and uses Copy-On-Write semantics. | ||
| It can be safely passed via public API. |
There was a problem hiding this comment.
Only if it has a Packed alias, I think :)
AThousandShips
added
enhancement
area:contributing
This continues #10329.
Packed*Arrayaliases seem universally preferred where available, so a link to the list of types seems appropriate.LocalVectoris used sparingly, so mentioning the intent and rough tradeoff involved seems right for an overview.Bugsquad edit: closes #6259.