Helper classes

[rh101]

I'm using a few helper classes at the moment in my own code, and I'm just wondering if there would be any benefit to adding them to the engine code.

Say you create an object of type Node to which you hold a local reference to it (with retain()), and you no longer require it in the scene, you would need to call the following methods:

node->removeFromParent();
AX_SAFE_RELEASE_NULL(node);

Or, if you use ax::RefPtr<Node>, then it would be:

node->removeFromParent();
node = nullptr;

Now, I've implemented SelfRemovingNodePtr, based on ax::RefPtr, but with a few additions. This would remove the node from the parent before releasing it, all within a single call:

node = nullptr;

There is also another one named SelfRemovingEventListenerPtr<T>, where T is of type EventListener, which will remove the event listener from the event dispatcher before releasing it, also reducing the number of calls to one:

eventListener = nullptr;

instead of

Director::getInstance()->getEventDispatcher()->removeEventListener(eventListener);
AX_SAFE_RELEASE_NULL(eventListener); // or `eventListener = nullptr` if ax::RefPtr is used

Would there be any benefit in adding these helper classes to the engine code? If yes, then the next question is, can someone think of better names for these classes (naming things is hard, and I hate naming things).

[aismann]

I think this helper can be usefull (that's the reason why you have create it).
Name:
why not "add/implement" it on:
AX_SAFE_RELEASE_NULL(xxx)

or call it
AX_SAFE_RELEASE_NODE
AX_SAFE_RELEASE_LISTENER

or call it
AX_SAFE_REMOVE_NODE
AX_SAFE_REMOVE_LISTENER

[rh101]

I think this helper can be usefull (that's the reason why you have create it). Name: why not "add/implement" it on:
or call it AX_SAFE_REMOVE_NODE AX_SAFE_REMOVE_LISTENER

I like that suggestion for naming, but those macros wouldn't be a replacement for the classes, but in addition to them.

The classes I referred to in my initial post are based on ax::RefPtr, which is a very helpful class, and removes the need for the AX_SAFE_RELEASE macros, since it automatically handles both the retain and release.

[DelinWorks]

this would be beneficial ngl, but the naming can be like this:

SelfRemoveNodePtr
SelfRemoveEventListenerPtr

Removing the present participle from the remove word is better imo

also.. one question, what is ax::RefPtr? it's the first time I've heard of it.. could you link an example because I didn't find anything about it in this repo.

[DelinWorks]

Actually, would these make sense:

RemovableNodePtr
RemovableEventListenerPtr

Less to type, with at least one possible downside; while they do indicate that they're removable, it doesn't indicate what does the removing.

I think that implies that the node is removable and without this class you won't be able to remove the node which might sound wrong.

[rh101]

Yep, that's downside.

I honestly cannot think of anything else at the moment other than the original names. Naming things is definitely hard.

[DelinWorks]

I think a good name would be AutoReleaseNodePtr maybe?.. although that might cause confusions with the method ax::Ref::autorelease()

[DelinWorks]

Come to think of it.. what's the difference between ax:RefPtr and Ref::autorelease function, wouldn't the autorelease function in ref do the job?

[rh101]

Come to think of it.. what's the difference between ax:RefPtr and Ref::autorelease function, wouldn't the autorelease function in ref do the job?

When autorelease() is called on a Ref object (Node, Sprite etc), it adds that object to the auto-release pool, and on the next cycle of the main loop the object will be removed from the pool. and the reference count decremented by 1. If that count equals 0, then the object is freed (release() is called on it).

ax::RefPtr has nothing to do with the auto-release pool, nor does it care if an object is set to be auto-released. What ax::RefPtr does is ensure that the object remains valid while you still have a reference to it in your own code, whether it is or isn't part of a scene, since it is responsible for explicitly calling retain() and release() on the object.

Example:

Node* node = Node::create();  // At this point, refCount = 1, and since the  create() method
// calls "autorelease()`, the object is in the auto-release pool
scene->addChild(node); // Now refCount = 2

On the next cycle of the main loop, the node that has been added to the scene is removed from the auto-release pool, and refCount decremented by 1, so now refCount = 1. Since refCount is not 0, the object is not deleted, as a reference is still held by the scene (addChild() calls retain() on the node).

Now, say you did this:

class myClass
{
   Node* _node;
}

// in the implementation:
this->_node = Node::create(); // refCount = 1

On the next loop, the auto-release code will decrement the reference count by 1, and since it's now equal to 0, the object is deleted, since nothing holds a reference to it. Then, you go ahead and reference this object in your code, for example:

_node->setPosition(x, y); // runtime crash here, since _node is no longer valid, and pointing 
    // to memory that was freed by the auto-release code
addChild(_node);

What needs to be done is retain this object, since we need to hold a reference to it:

class myClass
{
   Node* _node;
}

// in the implementation:
this->_node = Node::create(); // refCount = 1
_node->retain(); // refCount = 2

On the next loop, refCount will become 1, since the autorelease decremented it, yet it's still valid, since we hold a reference to it, so this will not crash:

_node->setPosition(x, y); // refCount = 1 here since the object was autoreleased in this loop, yet it's still valid
scene->addChild(_node); // now refCount becomes 2, since scene holds a reference, and so do we

When we're finally done with using it, we call release() on that node:

_node->release(); // refCount = 1, since the scene still has a reference
_node = nullptr; // to be safe so it's not pointing to invalid memory

or
AX_SAFE_RELEASE_NULL(_node); // which does the release and setting to nullptr

To make this all easier to manage, this is where ax::RefPtr comes into play:

class myClass
{
   ax::RefPtr<Node> _node;
}

// in the implementation:
this->_node = Node::create(); // refCount = 2, both from the retain in the autorelease() call, and retain() from the RefPtr

Next loop, _node refCount is 1, so it's still valid. When we're done with it, we just do this:

_node = nullptr; // release() is called by RefPtr, so it's reference count is decremented by 1. 
// If nothing else is holding a reference, the object is automatically freed