From 35779c6675728fa6f0fd0a21cefb904408509c23 Mon Sep 17 00:00:00 2001 From: Sebastien Bacher Date: Mon, 5 Jul 2021 20:35:03 +0200 Subject: New upstream version 1.32.2 --- docs/libnm/html/NMClient.html | 70 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 58 insertions(+), 12 deletions(-) (limited to 'docs/libnm/html/NMClient.html') diff --git a/docs/libnm/html/NMClient.html b/docs/libnm/html/NMClient.html index 7e7c131d..2fbd804a 100644 --- a/docs/libnm/html/NMClient.html +++ b/docs/libnm/html/NMClient.html @@ -1188,10 +1188,35 @@ nm_dns_entry_get_vpn (NMClient * nm_client_new (GCancellable *cancellable, GError **error); -

Creates a new NMClient.

-

Note that this will do blocking D-Bus calls to initialize the -client. You can use nm_client_new_async() if you want to avoid -that.

+

Creates a new NMClient synchronously.

+

Note that this will block until a NMClient instance is fully initialized. +This does nothing beside calling g_initable_new(). You are free to call +g_initable_new() or g_object_new()/g_initable_init() directly for more +control, to set GObject properties or get access to the NMClient instance +while it is still initializing.

+

Using the synchronous initialization creates an NMClient instance +that uses an internal GMainContext. This context is invisible to the +user. This introduces an additional overhead that is payed not +only during object initialization, but for the entire lifetime of +this object. +Also, due to this internal GMainContext, the events are no longer +in sync with other messages from GDBusConnection (but all events +of the NMClient will themselves still be ordered). +For a serious program, you should therefore avoid these problems by +using g_async_initable_init_async() or nm_client_new_async() instead. +The sync initialization is still useful for simple scripts or interactive +testing for example via pygobject.

+

Creating an NMClient instance can only fail for two reasons. First, if you didn't +provide a NM_CLIENT_DBUS_CONNECTION and the call to g_bus_get() +fails. You can avoid that by using g_initable_new() directly and +set a D-Bus connection. +Second, if you cancelled the creation. If you do that, then note +that after the failure there might still be idle actions pending +which keep nm_client_get_main_context() alive. That means, +in that case you must continue iterating the context to avoid +leaks. See nm_client_get_context_busy_watcher().

+

Creating an NMClient instance when NetworkManager is not running +does not cause a failure.

Parameters

@@ -1226,11 +1251,25 @@ that.

nm_client_new_async (GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); -

Creates a new NMClient and begins asynchronously initializing it. +

Creates a new NMClient asynchronously. callback - will be called when it is done; use -nm_client_new_finish() to get the result. Note that on an error, -the callback can be invoked with two first parameters as NULL.

+ will be called when it is done. Use +nm_client_new_finish() to get the result.

+

This does nothing beside calling g_async_initable_new_async(). You are free to +call g_async_initable_new_async() or g_object_new()/g_async_initable_init_async() +directly for more control, to set GObject properties or get access to the NMClient +instance while it is still initializing.

+

Creating an NMClient instance can only fail for two reasons. First, if you didn't +provide a NM_CLIENT_DBUS_CONNECTION and the call to g_bus_get() +fails. You can avoid that by using g_async_initable_new_async() directly and +set a D-Bus connection. +Second, if you cancelled the creation. If you do that, then note +that after the failure there might still be idle actions pending +which keep nm_client_get_main_context() alive. That means, +in that case you must continue iterating the context to avoid +leaks. See nm_client_get_context_busy_watcher().

+

Creating an NMClient instance when NetworkManager is not running +does not cause a failure.

Parameters

@@ -1416,14 +1455,21 @@ still outstanding and queued in the GMainContext. These outstanding callbacks keep the GMainContext alive. In order to fully release all resources, the user must keep iterating the main context until all these callbacks are handled. Of course, at this point no more actual callbacks will be invoked -for the user, those are all internally cancelled.

+for the user, those are all cancelled internally.

This just leaves one problem: how long does the user need to keep the GMainContext running to ensure everything is cleaned up? The answer is this GObject. Subscribe a weak reference to the returned object and keep iterating the main context until the object got unreferenced.

-

Note that after the NMClient instance gets destroyed, the remaining callbacks -will be invoked right away. That means, the user won't have to iterate the -main context much longer.

+

Note that after the NMClient instance gets destroyed, all outstanding operations +will be cancelled right away. That means, the user needs to iterate the GMainContext +a bit longer, but it is guaranteed that the cleanup happens soon after.

+

The way of using the context-busy-watch, is by registering a weak pointer to +see when it gets destroyed. That means, user code should not take additional +references on this object to not keep it alive longer.

+

If you plan to exit the program after releasing the NMClient instance +you may not need to worry about these "leaks". Also, if you anyway plan to continue +iterating the GMainContext afterwards, then you don't need to care when exactly +NMClient is gone completely.

[transfer none]

Since: 1.22

-- cgit 1.3.0-6-gf8a5