[Networkmanager] which objects under an NMClient must be freed

[Thomas Haller]

hi,

On Mon, 2023-02-27 at 16:00 +0000, VT102 wrote:
> Hello,
> I think I am not looking at the most up to date documentation, but
> was hoping for some clarification on which objects  need to be freed
> when using an NMClient with nmlib.
> 
> Current I allocate the following (below) objects in my logic, my
> understanding is that I do not need to free anything in this list
> except for the NMClient? I just wnated to get confirmation of this
> and maybe pointed to any documentation I missed that outlines this.
> Thanks
> 
> NMClient


NMClient is a cache of NMObject objects, that represent the current
data on NetworkManager's D-Bus API. Basically, NMClient fetches
devices, profiles, etc, and creates respective GObject/NMObject
instances that are in the cache.

NMClient manages the lifetime of these cached objects, and it will
unref when they go away. Also, when the NMClient itself gets destroted
(unref-ed), it will free all objects that it contains.

You may of course take additional references on those NMObject
instance, and of course they stay alive as long as you keep the
reference. Even if they are dropped from the NMClient cache (or if the
NMClient cache goes away). Call nm_object_get_client() to see whether
the object is still in the cache.

Also, some functions like
nm_client_add_and_activate_connection_finish() will return you an
additional reference to the object. You have to return that reference
when you are done. See the documentation for any function, whether you
are are transferred ownership of a reference.

The way to stop/shutdown/destroy the NMClient is just by unrefing it.
But note that NMClient hooks up to D-Bus signals, so it can only be
fully wrapped up by iterating the GMainContext/GMainLoop a bit longer.
That means, if you just unref the NMClient instance and not iterate the
GMainContext/GMainLoop anymore, then the NMClient is shutting down but
stays alive (leaks). That is no problem if your program is about to
quit. It would be a problem, if you want to keep running.
nm_client_wait_shutdown() can be used to know when NMClient is gone for
good (you still need to iterate the GMainContext/GMainLoop).



> NMConnection

NMConnection is a glib interface. There are two implementations:
NMSimpleConnection and NMRemoteConnection.

NMSimpleConnection is an object to represent the content of a profile.
It is commonly not in a NMClient cache and is not a subclass of
NMObject. Such an object is usually created by you, you own the 
reference and need to return the reference to it when you are done.

NMRemoteConnection is an NMObject, like

> NMActiveConnection
> NMRemoteConnection
> NMDevice

These also are NMObject subclasses. They are instantiated by NMClient,
and I don't think it ever makes sense for your application to create
them directly (with `g_object_new()`). What I said about NMClient above
applies.



Thomas