search

adventuregamestudio / ags-manual

AGS documentation.
https://adventuregamestudio.github.io/ags-manual/
MIT License
26 stars 9 forks source link

Clarify scoping and reference counting #211

Open ericoporto opened 1 year ago

ericoporto commented 1 year ago

I think there's only a mention here (the last sentence)

https://adventuregamestudio.github.io/ags-manual/ScriptKeywords.html#managed

When does the dynamic object gets destroyed? After you created dynamic object as described above, it will exist in memory as long as there is at least one pointer variable pointing to it. As soon as the last pointer gets destroyed itself (for example, if it was local function variable, and function ended), or is assigned another object, or simply assigned null, then the dynamic object is removed from your game forever.

We probably could add it's own "chapter" in the script language description to explain how this works, as it applies even to dynamic engine (and plugin) objects.

This sort of "runtime reference counting" is called garbage collection usually when I see in other languages. I don't know if the term applies to AGS Script too, as I am not sure if there are particulars to this. But if it is, it would be a good idea to use the term so people could find it in the index/search.

ivan-mogilko commented 1 year ago

There's an article on dynamic arrays, it may be used as an example of explaining certain moments, such as deletion.

Another related article is "Pointers in AGS".

This sort of "runtime reference counting" is called garbage collection usually when I see in other languages. I don't know if the term applies to AGS Script too, as I am not sure if there are particulars to this.

Yes, it applies, it's also called gc in the engine in few places, if i remember correctly.

One important thing to mention would be - internal engine's references. For example, Characters, and many other built-in objects, have 1 internal reference that is never lost, therefore these objects are not deleted even if no pointer remains valid in script.

ivan-mogilko commented 1 year ago

Another thing that I realized, usually it sais that the pointer is removed on function exit.

That is not accurate: the pointer is removed when its scope ends, which may be any block surrounded by {}, such as if, for, and so on. This is true for all the variables, of course.

The only place where I found information on variable's scope is here: https://github.com/adventuregamestudio/ags-manual/wiki/ScriptingTutorialPart1#variables

ericoporto commented 1 year ago

I will be honest, this is not an easy topic to grasp until it stings you. I have had things mysteriously fail until I realized it was a scope issue in JS and Python (specially in Qt and other libraries that bridge objects managed elsewhere, natively) for years. I will do some reading on how this is documented in other languages before I can figure it out how to approach this as being something referenced in the manual.

The links you added are good places to cross-reference using the see-also call-out we have.

One important thing to mention would be - internal engine's references.

Yeahp, this is a really good thing, thanks! This needs mentioning to clarify why they "behave differently".

We also have the plugin interface, where some implementation details are visible.

https://github.com/adventuregamestudio/ags-manual/wiki/EnginePluginRun-timeAPI#iagsengineincrementmanagedobjectrefcount