fdo-mirrors/NetworkManager
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/NetworkManager/NetworkManager.git synced 2026-01-02 07:40:12 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
NetworkManager/libnm/nm-manager.h
Thomas Haller e90684a169 libnm: deprecate synchronous/blocking API in libnm 
Note that D-Bus is fundamentally asynchronous. Doing blocking calls
on top of D-Bus is odd, especially for libnm's NMClient. That is because
NMClient essentially is a client-side cache of the objects from the D-Bus
interface. This cache should be filled exclusively by (asynchronous) D-Bus
events (PropertiesChanged). So, making a blocking D-Bus call means to wait
for a response and return it, while queuing all messages that are received
in the meantime.
Basically there are three ways how a synchronous API on NMClient could behave:

 1) the call just calls g_dbus_connection_call_sync(). This means
    that libnm sends a D-Bus request via GDBusConnection, and blockingly
    waits for the response. All D-Bus messages that get received in the
    meantime are queued in the GMainContext that belongs to NMClient.
    That means, none of these D-Bus events are processed until we
    iterate the GMainContext after the call returns. The effect is,
    that NMClient (and all cached objects in there) are unaffected by
    the D-Bus request.
    Most of the synchronous API calls in libnm are of this kind.
    The problem is that the strict ordering of D-Bus events gets
    violated.
    For some API this is not an immediate problem. Take for example
    nm_device_wifi_request_scan(). The call merely blockingly tells
    NetworkManager to start scanning, but since NetworkManager's D-Bus
    API does not directly expose any state that tells whether we are
    currently scanning, this out of order processing of the D-Bus
    request is a small issue.
    The problem is more obvious for nm_client_networking_set_enabled().
    After calling it, NM_CLIENT_NETWORKING_ENABLED is still unaffected
    and unchanged, because the PropertiesChanged signal from D-Bus
    is not yet processed.
    This means, while you make such a blocking call, NMClient's state
    does not change. But usually you perform the synchronous call
    to change some state. In this form, the blocking call is not useful,
    because NMClient only changes the state after iterating the GMainContext,
    and not after the blocking call returns.

 2) like 1), but after making the blocking g_dbus_connection_call_sync(),
    update the NMClient cache artificially. This is what
    nm_manager_check_connectivity() does, to "fix" bgo#784629.
    This also has the problem of out-of-order events, but it kinda
    solves the problem of not changing the state during the blocking
    call. But it does so by hacking the state of the cache. I think
    this is really wrong because the state should only be updated from
    the ordered stream of D-Bus messages (PropertiesChanged signal and
    similar). When libnm decides to modify the state, there may be already
    D-Bus messages queued that affect this very state.

 3) instead of calling g_dbus_connection_call_sync(), use the
    asynchronous g_dbus_connection_call(). If we would use a sepaate
    GMainContext for all D-Bus related calls, we could ensure that
    while we block for the response, we iterate that internal main context.
    This might be nice, because all events are processed in order and
    after the blocking call returns, the NMClient state is up to date.
    The are problems however: current blocking API does not do this,
    so it's a significant change in behavior. Also, it might be
    unexpected to the user that during the blocking call the entire
    content of NMClient's cache might change and all pointers to the
    cache might be invalidated. Also, of course NMClient would invoke
    signals for all the changes that happen.
    Another problem is that this would be more effort to implement
    and it involves a small performance overhead for all D-Bus related
    calls (because we have to serialize all events in an internal
    GMainContext first and then invoke them on the caller's context).
    Also, if the users wants this behavior, they could implement it themself
    by running libnm in their own GMainContext. Note that libnm might
    have bugs to make that really working, but that should be fixed
    instead of adding such synchrnous API behavior.

Read also [1], for why blocking calls are wrong.

[1] https://smcv.pseudorandom.co.uk/2008/11/nonblocking/

So, all possible behaviors for synchronous API have severe behavioural
issues.  Mark all this API as deprecated. Also, this serves the purpose of
identifying blocking D-Bus calls in libnm.

Note that "deprecated" here does not really mean that the API is going
to be removed. We don't break API. The user may:

  - continue to use this API. It's deprecated, awkward and discouraged,
    but if it works, by all means use it.

  - use asynchronous API. That's the only sensible way to use D-Bus.
    If libnm lacks a certain asynchronous counterpart, it should be
    added.

  - use GDBusConnection directly. There really isn't anything wrong
    with D-Bus or GDBusConnection. This deprecated API is just a wrapper
    around g_dbus_connection_call_sync(). You may call it directly
    without feeling dirty.

---

The only other remainging API is the synchronous GInitable call for
NMClient. That is an entirely separate beast and not particularly
wrong (from an API point of view).

Note that synchronous API in NMSecretAgentOld, NMVpnPluginOld and
NMVpnServicePlugin as not deprecated here. These types are not part
of the D-Bus cache and while they have similar issues, it's less severe
because they have less state.
2019-10-03 10:39:48 +02:00

254 lines
12 KiB
C
Raw Blame History

// SPDX-License-Identifier: LGPL-2.1+
/*
* Copyright (C) 2007 - 2008 Novell, Inc.
* Copyright (C) 2007 - 2014 Red Hat, Inc.
*/
#ifndef __NM_MANAGER_H__
#define __NM_MANAGER_H__
#if !((NETWORKMANAGER_COMPILATION) & NM_NETWORKMANAGER_COMPILATION_WITH_LIBNM_PRIVATE)
#error Cannot use this header.
#endif
#include "nm-object.h"
#include "nm-client.h"
#include "nm-libnm-utils.h"
#define NM_TYPE_MANAGER (nm_manager_get_type ())
#define NM_MANAGER(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), NM_TYPE_MANAGER, NMManager))
#define NM_MANAGER_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), NM_TYPE_MANAGER, NMManagerClass))
#define NM_IS_MANAGER(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), NM_TYPE_MANAGER))
#define NM_IS_MANAGER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), NM_TYPE_MANAGER))
#define NM_MANAGER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), NM_TYPE_MANAGER, NMManagerClass))
#define NM_MANAGER_VERSION "version"
#define NM_MANAGER_STATE "state"
#define NM_MANAGER_STARTUP "startup"
#define NM_MANAGER_NETWORKING_ENABLED "networking-enabled"
_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY_INTERNAL
#define NM_MANAGER_WIRELESS_ENABLED "wireless-enabled"
_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY_INTERNAL
#define NM_MANAGER_WWAN_ENABLED "wwan-enabled"
_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY_INTERNAL
#define NM_MANAGER_WIMAX_ENABLED "wimax-enabled"
#define NM_MANAGER_WIRELESS_HARDWARE_ENABLED "wireless-hardware-enabled"
#define NM_MANAGER_WWAN_HARDWARE_ENABLED "wwan-hardware-enabled"
#define NM_MANAGER_WIMAX_HARDWARE_ENABLED "wimax-hardware-enabled"
#define NM_MANAGER_ACTIVE_CONNECTIONS "active-connections"
#define NM_MANAGER_CONNECTIVITY "connectivity"
#define NM_MANAGER_CONNECTIVITY_CHECK_AVAILABLE "connectivity-check-available"
_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY_INTERNAL
#define NM_MANAGER_CONNECTIVITY_CHECK_ENABLED "connectivity-check-enabled"
#define NM_MANAGER_PRIMARY_CONNECTION "primary-connection"
#define NM_MANAGER_ACTIVATING_CONNECTION "activating-connection"
#define NM_MANAGER_DEVICES "devices"
#define NM_MANAGER_CHECKPOINTS "checkpoints"
#define NM_MANAGER_METERED "metered"
#define NM_MANAGER_ALL_DEVICES "all-devices"
/**
* NMManager:
*/
typedef struct {
NMObject parent;
} NMManager;
typedef struct {
NMObjectClass parent;
/* Signals */
void (*device_added) (NMManager *manager, NMDevice *device);
void (*device_removed) (NMManager *manager, NMDevice *device);
void (*active_connection_added) (NMManager *manager, NMActiveConnection *ac);
void (*active_connection_removed) (NMManager *manager, NMActiveConnection *ac);
void (*checkpoint_added) (NMManager *manager, NMCheckpoint *checkpoint);
void (*checkpoint_removed) (NMManager *manager, NMCheckpoint *checkpoint);
void (*permission_changed) (NMManager *manager,
NMClientPermission permission,
NMClientPermissionResult result);
} NMManagerClass;
GType nm_manager_get_type (void);
const char *nm_manager_get_version (NMManager *manager);
NMState nm_manager_get_state (NMManager *manager);
gboolean nm_manager_get_startup (NMManager *manager);
gboolean nm_manager_networking_get_enabled (NMManager *manager);
_NM_DEPRECATED_SYNC_METHOD_INTERNAL
gboolean nm_manager_networking_set_enabled (NMManager *manager,
gboolean enabled,
GError **error);
gboolean nm_manager_wireless_get_enabled (NMManager *manager);
_NM_DEPRECATED_SYNC_METHOD_INTERNAL
void nm_manager_wireless_set_enabled (NMManager *manager, gboolean enabled);
gboolean nm_manager_wireless_hardware_get_enabled (NMManager *manager);
gboolean nm_manager_wwan_get_enabled (NMManager *manager);
void nm_manager_wwan_set_enabled (NMManager *manager, gboolean enabled);
gboolean nm_manager_wwan_hardware_get_enabled (NMManager *manager);
gboolean nm_manager_wimax_get_enabled (NMManager *manager);
void nm_manager_wimax_set_enabled (NMManager *manager, gboolean enabled);
gboolean nm_manager_wimax_hardware_get_enabled (NMManager *manager);
gboolean nm_manager_connectivity_check_get_available (NMManager *manager);
gboolean nm_manager_connectivity_check_get_enabled (NMManager *manager);
void nm_manager_connectivity_check_set_enabled (NMManager *manager,
gboolean enabled);
const char *nm_manager_connectivity_check_get_uri (NMManager *manager);
gboolean nm_manager_get_logging (NMManager *manager,
char **level,
char **domains,
GError **error);
gboolean nm_manager_set_logging (NMManager *manager,
const char *level,
const char *domains,
GError **error);
NMClientPermissionResult nm_manager_get_permission_result (NMManager *manager,
NMClientPermission permission);
NMConnectivityState nm_manager_get_connectivity (NMManager *manager);
_NM_DEPRECATED_SYNC_METHOD_INTERNAL
NMConnectivityState nm_manager_check_connectivity (NMManager *manager,
GCancellable *cancellable,
GError **error);
void nm_manager_check_connectivity_async (NMManager *manager,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
NMConnectivityState nm_manager_check_connectivity_finish (NMManager *manager,
GAsyncResult *result,
GError **error);
/* Devices */
const GPtrArray *nm_manager_get_devices (NMManager *manager);
const GPtrArray *nm_manager_get_all_devices(NMManager *manager);
NMDevice *nm_manager_get_device_by_path (NMManager *manager, const char *object_path);
NMDevice *nm_manager_get_device_by_iface (NMManager *manager, const char *iface);
/* Active Connections */
const GPtrArray *nm_manager_get_active_connections (NMManager *manager);
NMActiveConnection *nm_manager_get_primary_connection (NMManager *manager);
NMActiveConnection *nm_manager_get_activating_connection (NMManager *manager);
void nm_manager_activate_connection_async (NMManager *manager,
NMConnection *connection,
NMDevice *device,
const char *specific_object,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
NMActiveConnection *nm_manager_activate_connection_finish (NMManager *manager,
GAsyncResult *result,
GError **error);
void nm_manager_add_and_activate_connection_async (NMManager *manager,
NMConnection *partial,
NMDevice *device,
const char *specific_object,
GVariant *options,
gboolean force_v2,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
NMActiveConnection *nm_manager_add_and_activate_connection_finish (NMManager *manager,
GAsyncResult *result,
GVariant **out_result,
GError **error);
_NM_DEPRECATED_SYNC_METHOD_INTERNAL
gboolean nm_manager_deactivate_connection (NMManager *manager,
NMActiveConnection *active,
GCancellable *cancellable,
GError **error);
void nm_manager_deactivate_connection_async (NMManager *manager,
NMActiveConnection *active,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
gboolean nm_manager_deactivate_connection_finish (NMManager *manager,
GAsyncResult *result,
GError **error);
const GPtrArray *nm_manager_get_checkpoints (NMManager *manager);
void nm_manager_checkpoint_create (NMManager *manager,
const GPtrArray *devices,
guint32 rollback_timeout,
NMCheckpointCreateFlags flags,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
NMCheckpoint *nm_manager_checkpoint_create_finish (NMManager *manager,
GAsyncResult *result,
GError **error);
void nm_manager_checkpoint_destroy (NMManager *manager,
const char *checkpoint_path,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
gboolean nm_manager_checkpoint_destroy_finish (NMManager *manager,
GAsyncResult *result,
GError **error);
void nm_manager_checkpoint_rollback (NMManager *manager,
const char *checkpoint_path,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
GHashTable *nm_manager_checkpoint_rollback_finish (NMManager *manager,
GAsyncResult *result,
GError **error);
void nm_manager_checkpoint_adjust_rollback_timeout (NMManager *manager,
const char *checkpoint_path,
guint32 add_timeout,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
gboolean nm_manager_checkpoint_adjust_rollback_timeout_finish (NMManager *manager,
GAsyncResult *result,
GError **error);
/*****************************************************************************/
typedef struct {
NMActiveConnection *active;
GVariant *add_and_activate_output;
} _NMActivateResult;
_NMActivateResult *_nm_activate_result_new (NMActiveConnection *active,
GVariant *add_and_activate_output);
void _nm_activate_result_free (_NMActivateResult *result);
/*****************************************************************************/
void nm_manager_reload (NMManager *manager,
NMManagerReloadFlags flags,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
gboolean nm_manager_reload_finish (NMManager *manager,
GAsyncResult *result,
GError **error);
#endif /* __NM_MANAGER_H__ */
Reference in a new issue View git blame Copy permalink