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.

13 files changed, 294 insertions, 8 deletions

diff --git a/docs/libnm/libnm-docs.xml b/docs/libnm/libnm-docs.xml
index b66e95ef5a..357cfe16d0 100644
--- a/docs/libnm/libnm-docs.xml
+++ b/docs/libnm/libnm-docs.xml
@@ -172,6 +172,125 @@ print ("NetworkManager version " + client.get_version())]]></programlisting></in
           <ulink url="https://gitlab.freedesktop.org/NetworkManager/NetworkManager/tree/master/examples">some examples</ulink>.
         </para>
       </simplesect>
+
+      <simplesect id="sync-api">
+        <title>Synchronous API in libnm</title>
+        <para>
+          Libnm contains some synchronous API. This API basically makes a blocking
+          D-Bus call (g_dbus_connection_call_sync()) and is now deprecated.
+        </para>
+        <para>
+          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 of the D-Bus
+          interface. This cache should be filled exclusively by (asynchronous) D-Bus
+          events. So, making a blocking D-Bus call means to wait for a response and
+          return it, while queuing everything that happens in between. Basically,
+          there are three options how a synchronous API on NMClient could behave:
+          <orderedlist>
+            <listitem>
+              <para>
+                The call basically 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.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                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. When libnm decides to modify
+                the state, there are already D-Bus messages queued that affect this
+                very state.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                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 the 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, they could implement it themself
+                using their own extra GMainContext and the asynchronous API.
+              </para>
+            </listitem>
+          </orderedlist>
+
+          See also <ulink url="https://smcv.pseudorandom.co.uk/2008/11/nonblocking/">this blog</ulink>
+          for why blocking calls are wrong.
+        </para>
+        <para>
+          All possible behaviors for synchronous API have severe behavioural
+          issues and thus such API is deprecated. Note that "deprecated" here does not
+          mean that the API is going to be removed. Libnm does not break API. The
+          user may:
+
+          <itemizedlist>
+            <listitem>
+              <para>
+                Continue to use this API. It's deprecated, awkward and discouraged,
+                but if it works for you, that's fine.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                Use asynchronous API. That's the only sensible way to use D-Bus.
+                If libnm lacks a certain asynchronous counterpart, it should be
+                added.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                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.
+              </para>
+            </listitem>
+          </itemizedlist>
+        </para>
+      </simplesect>
+
     </section>
   </chapter>
 
diff --git a/libnm-core/nm-version.h b/libnm-core/nm-version.h
index 5295778967..3180c7e26a 100644
--- a/libnm-core/nm-version.h
+++ b/libnm-core/nm-version.h
@@ -215,4 +215,30 @@
 # define NM_AVAILABLE_IN_1_22
 #endif
 
+/*
+ * Synchronous API for calling D-Bus in libnm is deprecated. See
+ * https://developer.gnome.org/libnm/stable/usage.html#sync-api
+ *
+ * Note that "deprecated" here does not really mean that the API is going
+ * to be removed. We don't break API. Just comment that it is awkward and
+ * discouraged. The user may:
+ *
+ *   - continue to use this API. It's deprecated, awkward and discouraged,
+ *     but if it works for you, that's fine.
+ *
+ *   - 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.
+ *
+ * We don't want to force users away from this API, for that reason the
+ * macro does not yet expand to G_DEPRECATED.
+ */
+#define _NM_DEPRECATED_SYNC_METHOD            /*NM_DEPRECATED_IN_1_22*/
+#define _NM_DEPRECATED_SYNC_WRITABLE_PROPERTY /*NM_DEPRECATED_IN_1_22*/
+
 #endif  /* NM_VERSION_H */
diff --git a/libnm/nm-client.c b/libnm/nm-client.c
index 567e014961..fd6c35dcae 100644
--- a/libnm/nm-client.c
+++ b/libnm/nm-client.c
@@ -291,12 +291,15 @@ nm_client_networking_get_enabled (NMClient *client)
  * all controlled interfaces are available for activation.
  *
  * Returns: %TRUE on success, %FALSE otherwise
+ *
+ * Deprecated: 1.22, use nm_client_networking_set_enabled_async() or GDBusConnection
  **/
 gboolean
 nm_client_networking_set_enabled (NMClient *client, gboolean enable, GError **error)
 {
 	g_return_val_if_fail (NM_IS_CLIENT (client), FALSE);
 
+	/* FIXME(libnm-async-api): add nm_client_networking_set_enabled_async(). */
 	if (!_nm_client_check_nm_running (client, error))
 		return FALSE;
 
@@ -329,12 +332,15 @@ nm_client_wireless_get_enabled (NMClient *client)
  * @enabled: %TRUE to enable wireless
  *
  * Enables or disables wireless devices.
- **/
+ *
+ * Deprecated: 1.22, use nm_client_wireless_set_enabled_async() or GDBusConnection
+ */
 void
 nm_client_wireless_set_enabled (NMClient *client, gboolean enabled)
 {
 	g_return_if_fail (NM_IS_CLIENT (client));
 
+	/* FIXME(libnm-async-api): add nm_client_wireless_set_enabled_async(). */
 	if (!nm_client_get_nm_running (client))
 		return;
 
@@ -669,6 +675,8 @@ nm_client_get_connectivity (NMClient *client)
  * if you do not want to block.
  *
  * Returns: the (new) current connectivity state
+ *
+ * Deprecated: 1.22, use nm_client_check_connectivity_async() or GDBusConnection
  */
 NMConnectivityState
 nm_client_check_connectivity (NMClient *client,
@@ -780,6 +788,8 @@ nm_client_check_connectivity_finish (NMClient *client,
  * or cleared.
  *
  * Returns: %TRUE if the request was successful, %FALSE if it failed
+ *
+ * Deprecated: 1.22, use nm_client_save_hostname_async() or GDBusConnection
  **/
 gboolean
 nm_client_save_hostname (NMClient *client,
@@ -1417,6 +1427,8 @@ nm_client_add_and_activate_connection2_finish (NMClient *client,
  * Deactivates an active #NMActiveConnection.
  *
  * Returns: success or failure
+ *
+ * Deprecated: 1.22, use nm_client_deactivate_connection_async() or GDBusConnection
  **/
 gboolean
 nm_client_deactivate_connection (NMClient *client,
@@ -1878,6 +1890,8 @@ nm_client_add_connection2_finish (NMClient *client,
  *
  * Returns: %TRUE if NetworkManager at least tried to load @filenames,
  * %FALSE if an error occurred (eg, permission denied).
+ *
+ * Deprecated: 1.22, use nm_client_load_connections_async() or GDBusConnection
  **/
 gboolean
 nm_client_load_connections (NMClient *client,
@@ -2001,6 +2015,8 @@ nm_client_load_connections_finish (NMClient *client,
  * the in-memory state matches the on-disk state.
  *
  * Return value: %TRUE on success, %FALSE on failure
+ *
+ * Deprecated: 1.22, use nm_client_reload_connections_async() or GDBusConnection
  **/
 gboolean
 nm_client_reload_connections (NMClient *client,
@@ -3661,7 +3677,9 @@ nm_client_class_init (NMClientClass *client_class)
 	 * NMClient:networking-enabled:
 	 *
 	 * Whether networking is enabled.
-	 **/
+	 *
+	 * The property setter is a synchronous D-Bus call. This is deprecated since 1.22.
+	 */
 	g_object_class_install_property
 		(object_class, PROP_NETWORKING_ENABLED,
 		 g_param_spec_boolean (NM_CLIENT_NETWORKING_ENABLED, "", "",
@@ -3673,6 +3691,8 @@ nm_client_class_init (NMClientClass *client_class)
 	 * NMClient:wireless-enabled:
 	 *
 	 * Whether wireless is enabled.
+	 *
+	 * The property setter is a synchronous D-Bus call. This is deprecated since 1.22.
 	 **/
 	g_object_class_install_property
 		(object_class, PROP_WIRELESS_ENABLED,
@@ -3697,7 +3717,9 @@ nm_client_class_init (NMClientClass *client_class)
 	 * NMClient:wwan-enabled:
 	 *
 	 * Whether WWAN functionality is enabled.
-	 **/
+	 *
+	 * The property setter is a synchronous D-Bus call. This is deprecated since 1.22.
+	 */
 	g_object_class_install_property
 		(object_class, PROP_WWAN_ENABLED,
 		 g_param_spec_boolean (NM_CLIENT_WWAN_ENABLED, "", "",
@@ -3721,7 +3743,9 @@ nm_client_class_init (NMClientClass *client_class)
 	 * NMClient:wimax-enabled:
 	 *
 	 * Whether WiMAX functionality is enabled.
-	 **/
+	 *
+	 * The property setter is a synchronous D-Bus call. This is deprecated since 1.22.
+	 */
 	g_object_class_install_property
 		(object_class, PROP_WIMAX_ENABLED,
 		 g_param_spec_boolean (NM_CLIENT_WIMAX_ENABLED, "", "",
@@ -3786,6 +3810,8 @@ nm_client_class_init (NMClientClass *client_class)
 	 * Whether a connectivity checking service has been enabled.
 	 *
 	 * Since: 1.10
+	 *
+	 * The property setter is a synchronous D-Bus call. This is deprecated since 1.22.
 	 */
 	g_object_class_install_property
 		(object_class, PROP_CONNECTIVITY_CHECK_ENABLED,
diff --git a/libnm/nm-client.h b/libnm/nm-client.h
index faa7d825d8..6e6d883e78 100644
--- a/libnm/nm-client.h
+++ b/libnm/nm-client.h
@@ -26,17 +26,28 @@ G_BEGIN_DECLS
 #define NM_CLIENT_STATE "state"
 #define NM_CLIENT_STARTUP "startup"
 #define NM_CLIENT_NM_RUNNING "nm-running"
+
+_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY
 #define NM_CLIENT_NETWORKING_ENABLED "networking-enabled"
+
+_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY
 #define NM_CLIENT_WIRELESS_ENABLED "wireless-enabled"
-#define NM_CLIENT_WIRELESS_HARDWARE_ENABLED "wireless-hardware-enabled"
+_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY
 #define NM_CLIENT_WWAN_ENABLED "wwan-enabled"
-#define NM_CLIENT_WWAN_HARDWARE_ENABLED "wwan-hardware-enabled"
+_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY
 #define NM_CLIENT_WIMAX_ENABLED "wimax-enabled"
+
+#define NM_CLIENT_WIRELESS_HARDWARE_ENABLED "wireless-hardware-enabled"
+#define NM_CLIENT_WWAN_HARDWARE_ENABLED "wwan-hardware-enabled"
 #define NM_CLIENT_WIMAX_HARDWARE_ENABLED "wimax-hardware-enabled"
+
 #define NM_CLIENT_ACTIVE_CONNECTIONS "active-connections"
 #define NM_CLIENT_CONNECTIVITY "connectivity"
 #define NM_CLIENT_CONNECTIVITY_CHECK_AVAILABLE "connectivity-check-available"
+
+_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY
 #define NM_CLIENT_CONNECTIVITY_CHECK_ENABLED "connectivity-check-enabled"
+
 #define NM_CLIENT_PRIMARY_CONNECTION "primary-connection"
 #define NM_CLIENT_ACTIVATING_CONNECTION "activating-connection"
 #define NM_CLIENT_DEVICES "devices"
@@ -225,20 +236,31 @@ gboolean    nm_client_get_startup    (NMClient *client);
 gboolean    nm_client_get_nm_running (NMClient *client);
 
 gboolean nm_client_networking_get_enabled (NMClient *client);
+
+_NM_DEPRECATED_SYNC_METHOD
 gboolean nm_client_networking_set_enabled (NMClient *client,
                                            gboolean enabled,
                                            GError **error);
 
 gboolean nm_client_wireless_get_enabled (NMClient *client);
+
+_NM_DEPRECATED_SYNC_METHOD
 void     nm_client_wireless_set_enabled (NMClient *client, gboolean enabled);
+
 gboolean nm_client_wireless_hardware_get_enabled (NMClient *client);
 
 gboolean nm_client_wwan_get_enabled (NMClient *client);
+
+_NM_DEPRECATED_SYNC_METHOD
 void     nm_client_wwan_set_enabled (NMClient *client, gboolean enabled);
+
 gboolean nm_client_wwan_hardware_get_enabled (NMClient *client);
 
 gboolean nm_client_wimax_get_enabled (NMClient *client);
+
+_NM_DEPRECATED_SYNC_METHOD
 void     nm_client_wimax_set_enabled (NMClient *client, gboolean enabled);
+
 gboolean nm_client_wimax_hardware_get_enabled (NMClient *client);
 
 NM_AVAILABLE_IN_1_10
@@ -248,6 +270,7 @@ NM_AVAILABLE_IN_1_10
 gboolean nm_client_connectivity_check_get_enabled (NMClient *client);
 
 NM_AVAILABLE_IN_1_10
+_NM_DEPRECATED_SYNC_METHOD
 void     nm_client_connectivity_check_set_enabled (NMClient *client,
                                                    gboolean enabled);
 
@@ -268,9 +291,11 @@ NMClientPermissionResult nm_client_get_permission_result (NMClient *client,
 
 NMConnectivityState nm_client_get_connectivity          (NMClient *client);
 
+_NM_DEPRECATED_SYNC_METHOD
 NMConnectivityState nm_client_check_connectivity        (NMClient *client,
                                                          GCancellable *cancellable,
                                                          GError **error);
+
 void                nm_client_check_connectivity_async  (NMClient *client,
                                                          GCancellable *cancellable,
                                                          GAsyncReadyCallback callback,
@@ -279,10 +304,12 @@ NMConnectivityState nm_client_check_connectivity_finish (NMClient *client,
                                                          GAsyncResult *result,
                                                          GError **error);
 
+_NM_DEPRECATED_SYNC_METHOD
 gboolean nm_client_save_hostname        (NMClient *client,
                                          const char *hostname,
                                          GCancellable *cancellable,
                                          GError **error);
+
 void     nm_client_save_hostname_async  (NMClient *client,
                                          const char *hostname,
                                          GCancellable *cancellable,
@@ -344,10 +371,12 @@ NMActiveConnection *nm_client_add_and_activate_connection2_finish (NMClient *cli
                                                                    GVariant **out_result,
                                                                    GError **error);
 
+_NM_DEPRECATED_SYNC_METHOD
 gboolean nm_client_deactivate_connection        (NMClient *client,
                                                  NMActiveConnection *active,
                                                  GCancellable *cancellable,
                                                  GError **error);
+
 void     nm_client_deactivate_connection_async  (NMClient *client,
                                                  NMActiveConnection *active,
                                                  GCancellable *cancellable,
@@ -391,11 +420,13 @@ NMRemoteConnection *nm_client_add_connection2_finish (NMClient *client,
                                                       GVariant **out_result,
                                                       GError **error);
 
+_NM_DEPRECATED_SYNC_METHOD
 gboolean nm_client_load_connections        (NMClient *client,
                                             char **filenames,
                                             char ***failures,
                                             GCancellable *cancellable,
                                             GError **error);
+
 void     nm_client_load_connections_async  (NMClient *client,
                                             char **filenames,
                                             GCancellable *cancellable,
@@ -406,9 +437,11 @@ gboolean nm_client_load_connections_finish (NMClient *client,
                                             GAsyncResult *result,
                                             GError **error);
 
+_NM_DEPRECATED_SYNC_METHOD
 gboolean nm_client_reload_connections        (NMClient *client,
                                               GCancellable *cancellable,
                                               GError **error);
+
 void     nm_client_reload_connections_async  (NMClient *client,
                                               GCancellable *cancellable,
                                               GAsyncReadyCallback callback,
diff --git a/libnm/nm-device-wifi.c b/libnm/nm-device-wifi.c
index f37ef69fa6..30dbd09f89 100644
--- a/libnm/nm-device-wifi.c
+++ b/libnm/nm-device-wifi.c
@@ -331,6 +331,8 @@ _device_wifi_request_scan (NMDeviceWifi *device,
  *
  * Returns: %TRUE on success, %FALSE on error, in which case @error will be
  * set.
+ *
+ * Deprecated: 1.22, use nm_device_wifi_request_scan_async() or GDBusConnection
  **/
 gboolean
 nm_device_wifi_request_scan (NMDeviceWifi *device,
@@ -359,6 +361,8 @@ nm_device_wifi_request_scan (NMDeviceWifi *device,
  * set.
  *
  * Since: 1.2
+ *
+ * Deprecated: 1.22, use nm_device_wifi_request_scan_options_async() or GDBusConnection
  **/
 gboolean
 nm_device_wifi_request_scan_options (NMDeviceWifi *device,
diff --git a/libnm/nm-device-wifi.h b/libnm/nm-device-wifi.h
index d875486673..18ebf24ccc 100644
--- a/libnm/nm-device-wifi.h
+++ b/libnm/nm-device-wifi.h
@@ -66,10 +66,12 @@ const GPtrArray *        nm_device_wifi_get_access_points        (NMDeviceWifi *
 NM_AVAILABLE_IN_1_12
 gint64                   nm_device_wifi_get_last_scan            (NMDeviceWifi *device);
 
+_NM_DEPRECATED_SYNC_METHOD
 gboolean                 nm_device_wifi_request_scan             (NMDeviceWifi *device,
                                                                   GCancellable *cancellable,
                                                                   GError **error);
 NM_AVAILABLE_IN_1_2
+_NM_DEPRECATED_SYNC_METHOD
 gboolean                 nm_device_wifi_request_scan_options     (NMDeviceWifi *device,
                                                                   GVariant *options,
                                                                   GCancellable *cancellable,
diff --git a/libnm/nm-device.c b/libnm/nm-device.c
index 90534e33bc..4acbfbce91 100644
--- a/libnm/nm-device.c
+++ b/libnm/nm-device.c
@@ -610,6 +610,8 @@ nm_device_class_init (NMDeviceClass *device_class)
 	 * NMDevice:autoconnect:
 	 *
 	 * Whether the device can auto-activate a connection.
+	 *
+	 * The property setter is a synchronous D-Bus call. This is deprecated since 1.22.
 	 **/
 	g_object_class_install_property
 		(object_class, PROP_AUTOCONNECT,
@@ -1087,12 +1089,16 @@ nm_device_get_managed (NMDevice *device)
  * Enables or disables management of  #NMDevice by NetworkManager.
  *
  * Since: 1.2
+ *
+ * Deprecated: 1.22, use nm_device_set_managed_async() or GDBusConnection
  **/
 void
 nm_device_set_managed (NMDevice *device, gboolean managed)
 {
 	g_return_if_fail (NM_IS_DEVICE (device));
 
+	/* FIXME(libnm-async-api): add nm_device_set_managed_async(). */
+
 	managed = !!managed;
 
 	NM_DEVICE_GET_PRIVATE (device)->managed = managed;
@@ -1125,12 +1131,16 @@ nm_device_get_autoconnect (NMDevice *device)
  * @autoconnect: %TRUE to enable autoconnecting
  *
  * Enables or disables automatic activation of the #NMDevice.
+ *
+ * Deprecated: 1.22, use nm_device_set_autoconnect_async() or GDBusConnection
  **/
 void
 nm_device_set_autoconnect (NMDevice *device, gboolean autoconnect)
 {
 	g_return_if_fail (NM_IS_DEVICE (device));
 
+	/* FIXME(libnm-async-api): add nm_device_set_autoconnect_async(). */
+
 	NM_DEVICE_GET_PRIVATE (device)->autoconnect = autoconnect;
 
 	_nm_object_set_property (NM_OBJECT (device),
@@ -1988,6 +1998,8 @@ nm_device_is_software (NMDevice *device)
  * Returns: %TRUE on success, %FALSE on error, in which case @error will be set.
  *
  * Since: 1.2
+ *
+ * Deprecated: 1.22, use nm_device_reapply_async() or GDBusConnection
  **/
 gboolean
 nm_device_reapply (NMDevice *device,
@@ -2130,6 +2142,8 @@ nm_device_reapply_finish (NMDevice *device,
  * to nm_connection_verify().
  *
  * Since: 1.2
+ *
+ * Deprecated: 1.22, use nm_device_get_applied_connection_async() or GDBusConnection
  **/
 NMConnection *
 nm_device_get_applied_connection (NMDevice *device,
@@ -2302,6 +2316,8 @@ nm_device_get_applied_connection_finish (NMDevice *device,
  * request.
  *
  * Returns: %TRUE on success, %FALSE on error, in which case @error will be set.
+ *
+ * Deprecated: 1.22, use nm_device_disconnect_async() or GDBusConnection
  **/
 gboolean
 nm_device_disconnect (NMDevice *device,
@@ -2406,6 +2422,8 @@ nm_device_disconnect_finish (NMDevice *device,
  *
  * Returns: %TRUE on success, %FALSE on error, in which case @error
  * will be set.
+ *
+ * Deprecated: 1.22, use nm_device_delete_async() or GDBusConnection
  **/
 gboolean
 nm_device_delete (NMDevice *device,
diff --git a/libnm/nm-device.h b/libnm/nm-device.h
index b5343bd243..5d8a1cae6e 100644
--- a/libnm/nm-device.h
+++ b/libnm/nm-device.h
@@ -32,7 +32,10 @@ G_BEGIN_DECLS
 #define NM_DEVICE_CAPABILITIES "capabilities"
 #define NM_DEVICE_REAL "real"
 #define NM_DEVICE_MANAGED "managed"
+
+_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY
 #define NM_DEVICE_AUTOCONNECT "autoconnect"
+
 #define NM_DEVICE_FIRMWARE_MISSING "firmware-missing"
 #define NM_DEVICE_NM_PLUGIN_MISSING "nm-plugin-missing"
 #define NM_DEVICE_IP4_CONFIG "ip4-config"
@@ -97,10 +100,16 @@ const char *         nm_device_get_type_description (NMDevice *device);
 const char *         nm_device_get_hw_address       (NMDevice *device);
 NMDeviceCapabilities nm_device_get_capabilities     (NMDevice *device);
 gboolean             nm_device_get_managed          (NMDevice *device);
+
 NM_AVAILABLE_IN_1_2
+_NM_DEPRECATED_SYNC_METHOD
 void                 nm_device_set_managed          (NMDevice *device, gboolean managed);
+
 gboolean             nm_device_get_autoconnect      (NMDevice *device);
+
+_NM_DEPRECATED_SYNC_METHOD
 void                 nm_device_set_autoconnect      (NMDevice *device, gboolean autoconnect);
+
 gboolean             nm_device_get_firmware_missing (NMDevice *device);
 NM_AVAILABLE_IN_1_2
 gboolean             nm_device_get_nm_plugin_missing (NMDevice *device);
@@ -130,6 +139,7 @@ GPtrArray *          nm_device_get_lldp_neighbors    (NMDevice *device);
 char **              nm_device_disambiguate_names    (NMDevice **devices,
                                                       int        num_devices);
 NM_AVAILABLE_IN_1_2
+_NM_DEPRECATED_SYNC_METHOD
 gboolean             nm_device_reapply              (NMDevice *device,
                                                      NMConnection *connection,
                                                      guint64 version_id,
@@ -150,6 +160,7 @@ gboolean             nm_device_reapply_finish       (NMDevice *device,
                                                      GError **error);
 
 NM_AVAILABLE_IN_1_2
+_NM_DEPRECATED_SYNC_METHOD
 NMConnection        *nm_device_get_applied_connection (NMDevice *device,
                                                        guint32 flags,
                                                        guint64 *version_id,
@@ -167,6 +178,7 @@ NMConnection        *nm_device_get_applied_connection_finish (NMDevice *device,
                                                               guint64 *version_id,
                                                               GError **error);
 
+_NM_DEPRECATED_SYNC_METHOD
 gboolean             nm_device_disconnect           (NMDevice *device,
                                                      GCancellable *cancellable,
                                                      GError **error);
@@ -178,6 +190,7 @@ gboolean             nm_device_disconnect_finish    (NMDevice *device,
                                                      GAsyncResult *result,
                                                      GError **error);
 
+_NM_DEPRECATED_SYNC_METHOD
 gboolean             nm_device_delete               (NMDevice *device,
                                                      GCancellable *cancellable,
                                                      GError **error);
diff --git a/libnm/nm-libnm-utils.h b/libnm/nm-libnm-utils.h
index 35684117fd..5dc579010a 100644
--- a/libnm/nm-libnm-utils.h
+++ b/libnm/nm-libnm-utils.h
@@ -10,6 +10,10 @@
 #error Cannot use this header.
 #endif
 
+/* Markers for deprecated sync code in internal API. */
+#define _NM_DEPRECATED_SYNC_METHOD_INTERNAL            NM_DEPRECATED_IN_1_22
+#define _NM_DEPRECATED_SYNC_WRITABLE_PROPERTY_INTERNAL NM_DEPRECATED_IN_1_22
+
 char *nm_utils_fixup_vendor_string (const char *desc);
 char *nm_utils_fixup_product_string (const char *desc);
 
diff --git a/libnm/nm-manager.h b/libnm/nm-manager.h
index 54a06b0019..9b46b6417d 100644
--- a/libnm/nm-manager.h
+++ b/libnm/nm-manager.h
@@ -13,6 +13,7 @@
 
 #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))
@@ -25,16 +26,26 @@
 #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"
-#define NM_MANAGER_WIRELESS_HARDWARE_ENABLED "wireless-hardware-enabled"
+
+_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY_INTERNAL
 #define NM_MANAGER_WWAN_ENABLED "wwan-enabled"
-#define NM_MANAGER_WWAN_HARDWARE_ENABLED "wwan-hardware-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"
@@ -71,12 +82,17 @@ 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);
@@ -110,6 +126,7 @@ NMClientPermissionResult nm_manager_get_permission_result (NMManager *manager,
 
 NMConnectivityState nm_manager_get_connectivity          (NMManager *manager);
 
+_NM_DEPRECATED_SYNC_METHOD_INTERNAL
 NMConnectivityState nm_manager_check_connectivity        (NMManager *manager,
                                                           GCancellable *cancellable,
                                                           GError **error);
@@ -160,6 +177,7 @@ NMActiveConnection *nm_manager_add_and_activate_connection_finish (NMManager *ma
                                                                    GVariant **out_result,
                                                                    GError **error);
 
+_NM_DEPRECATED_SYNC_METHOD_INTERNAL
 gboolean nm_manager_deactivate_connection        (NMManager *manager,
                                                   NMActiveConnection *active,
                                                   GCancellable *cancellable,
diff --git a/libnm/nm-remote-connection.c b/libnm/nm-remote-connection.c
index 7d1aa1a1ea..04fbd3b170 100644
--- a/libnm/nm-remote-connection.c
+++ b/libnm/nm-remote-connection.c
@@ -181,6 +181,8 @@ nm_remote_connection_update2_finish (NMRemoteConnection *connection,
  * disk; if %FALSE, then only the in-memory representation will be changed.
  *
  * Returns: %TRUE on success, %FALSE on error, in which case @error will be set.
+ *
+ * Deprecated: 1.22, use nm_remote_connection_commit_changes_async() or GDBusConnection
  **/
 gboolean
 nm_remote_connection_commit_changes (NMRemoteConnection *connection,
@@ -317,6 +319,8 @@ nm_remote_connection_commit_changes_finish (NMRemoteConnection *connection,
  * been written to disk, or if the connection has never been saved.
  *
  * Returns: %TRUE on success, %FALSE on error, in which case @error will be set.
+ *
+ * Deprecated: 1.22, use nm_remote_connection_save_async() or GDBusConnection
  **/
 gboolean
 nm_remote_connection_save (NMRemoteConnection *connection,
@@ -420,6 +424,8 @@ nm_remote_connection_save_finish (NMRemoteConnection *connection,
  * Deletes the connection.
  *
  * Returns: %TRUE on success, %FALSE on error, in which case @error will be set.
+ *
+ * Deprecated: 1.22, use nm_remote_connection_delete_async() or GDBusConnection
  **/
 gboolean
 nm_remote_connection_delete (NMRemoteConnection *connection,
@@ -523,6 +529,8 @@ nm_remote_connection_delete_finish (NMRemoteConnection *connection,
  *
  * Returns: a #GVariant of type %NM_VARIANT_TYPE_CONNECTION containing
  * @connection's secrets, or %NULL on error.
+ *
+ * Deprecated: 1.22, use nm_remote_connection_get_secrets_async() or GDBusConnection
  **/
 GVariant *
 nm_remote_connection_get_secrets (NMRemoteConnection *connection,
diff --git a/libnm/nm-remote-connection.h b/libnm/nm-remote-connection.h
index 37ab154e95..ce6eef993d 100644
--- a/libnm/nm-remote-connection.h
+++ b/libnm/nm-remote-connection.h
@@ -59,10 +59,12 @@ GVariant *nm_remote_connection_update2_finish (NMRemoteConnection *connection,
                                                GAsyncResult *result,
                                                GError **error);
 
+_NM_DEPRECATED_SYNC_METHOD
 gboolean nm_remote_connection_commit_changes        (NMRemoteConnection *connection,
                                                      gboolean save_to_disk,
                                                      GCancellable *cancellable,
                                                      GError **error);
+
 void     nm_remote_connection_commit_changes_async  (NMRemoteConnection *connection,
                                                      gboolean save_to_disk,
                                                      GCancellable *cancellable,
@@ -72,9 +74,11 @@ gboolean nm_remote_connection_commit_changes_finish (NMRemoteConnection *connect
                                                      GAsyncResult *result,
                                                      GError **error);
 
+_NM_DEPRECATED_SYNC_METHOD
 gboolean nm_remote_connection_save        (NMRemoteConnection *connection,
                                            GCancellable *cancellable,
                                            GError **error);
+
 void     nm_remote_connection_save_async  (NMRemoteConnection *connection,
                                            GCancellable *cancellable,
                                            GAsyncReadyCallback callback,
@@ -83,9 +87,11 @@ gboolean nm_remote_connection_save_finish (NMRemoteConnection *connection,
                                            GAsyncResult *result,
                                            GError **error);
 
+_NM_DEPRECATED_SYNC_METHOD
 gboolean nm_remote_connection_delete        (NMRemoteConnection *connection,
                                              GCancellable *cancellable,
                                              GError **error);
+
 void     nm_remote_connection_delete_async  (NMRemoteConnection *connection,
                                              GCancellable *cancellable,
                                              GAsyncReadyCallback callback,
@@ -94,10 +100,12 @@ gboolean nm_remote_connection_delete_finish (NMRemoteConnection *connection,
                                              GAsyncResult *result,
                                              GError **error);
 
+_NM_DEPRECATED_SYNC_METHOD
 GVariant *nm_remote_connection_get_secrets        (NMRemoteConnection *connection,
                                                    const char *setting_name,
                                                    GCancellable *cancellable,
                                                    GError **error);
+
 void      nm_remote_connection_get_secrets_async  (NMRemoteConnection *connection,
                                                    const char *setting_name,
                                                    GCancellable *cancellable,
diff --git a/libnm/nm-remote-settings.h b/libnm/nm-remote-settings.h
index 180e900880..6006a53b56 100644
--- a/libnm/nm-remote-settings.h
+++ b/libnm/nm-remote-settings.h
@@ -12,6 +12,7 @@
 #endif
 
 #include "nm-object.h"
+#include "nm-libnm-utils.h"
 
 #define NM_TYPE_REMOTE_SETTINGS            (nm_remote_settings_get_type ())
 #define NM_REMOTE_SETTINGS(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), NM_TYPE_REMOTE_SETTINGS, NMRemoteSettings))
@@ -74,11 +75,13 @@ void nm_remote_settings_add_connection2 (NMRemoteSettings *self,
                                          NMRemoteSettingAddConnection2Callback callback,
                                          gpointer user_data);
 
+_NM_DEPRECATED_SYNC_METHOD_INTERNAL
 gboolean nm_remote_settings_load_connections        (NMRemoteSettings *settings,
                                                      char **filenames,
                                                      char ***failures,
                                                      GCancellable *cancellable,
                                                      GError **error);
+
 void     nm_remote_settings_load_connections_async  (NMRemoteSettings *settings,
                                                      char **filenames,
                                                      GCancellable *cancellable,
@@ -89,9 +92,11 @@ gboolean nm_remote_settings_load_connections_finish (NMRemoteSettings *settings,
                                                      GAsyncResult *result,
                                                      GError **error);
 
+_NM_DEPRECATED_SYNC_METHOD_INTERNAL
 gboolean nm_remote_settings_reload_connections        (NMRemoteSettings *settings,
                                                        GCancellable *cancellable,
                                                        GError **error);
+
 void     nm_remote_settings_reload_connections_async  (NMRemoteSettings *settings,
                                                        GCancellable *cancellable,
                                                        GAsyncReadyCallback callback,
@@ -100,10 +105,12 @@ gboolean nm_remote_settings_reload_connections_finish (NMRemoteSettings *setting
                                                        GAsyncResult *result,
                                                        GError **error);
 
+_NM_DEPRECATED_SYNC_METHOD_INTERNAL
 gboolean nm_remote_settings_save_hostname        (NMRemoteSettings *settings,
                                                   const char *hostname,
                                                   GCancellable *cancellable,
                                                   GError **error);
+
 void     nm_remote_settings_save_hostname_async  (NMRemoteSettings *settings,
                                                   const char *hostname,
                                                   GCancellable *cancellable,