gio/gpowerprofilemonitor.c

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright 2019 Red Hat, Inc
   4  * Copyright 2021 Igalia S.L.
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General
  17  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 #include "config.h"
  21 #include "glib.h"
  22 #include "glibintl.h"
  23
  24 #include "gpowerprofilemonitor.h"
  25 #include "ginetaddress.h"
  26 #include "ginetsocketaddress.h"
  27 #include "ginitable.h"
  28 #include "gioenumtypes.h"
  29 #include "giomodule-priv.h"
  30 #include "gtask.h"
  31
  32 /**
  33  * SECTION:gpowerprofilemonitor
  34  * @title: GPowerProfileMonitor
  35  * @short_description: Power profile monitor
  36  * @include: gio/gio.h
  37  *
  38  * #GPowerProfileMonitor makes it possible for applications as well as OS components
  39  * to monitor system power profiles and act upon them. It currently only exports
  40  * whether the system is in “Power Saver” mode (known as “Low Power” mode on
  41  * some systems).
  42  *
  43  * When in “Low Power” mode, it is recommended that applications:
  44  * - disabling automatic downloads
  45  * - reduce the rate of refresh from online sources such as calendar or
  46  *   email synchronisation
  47  * - if the application has expensive visual effects, reduce them
  48  *
  49  * It is also likely that OS components providing services to applications will
  50  * lower their own background activity, for the sake of the system.
  51  *
  52  * There are a variety of tools that exist for power consumption analysis, but those
  53  * usually depend on the OS and hardware used. On Linux, one could use `upower` to
  54  * monitor the battery discharge rate, `powertop` to check on the background activity
  55  * or activity at all), `sysprof` to inspect CPU usage, and `intel_gpu_time` to
  56  * profile GPU usage.
  57  *
  58  * Don't forget to disconnect the #GPowerProfileMonitor::notify::power-saver-enabled
  59  * signal, and unref the #GPowerProfileMonitor itself when exiting.
  60  *
  61  * Since: 2.70
  62  */
  63
  64 /**
  65  * GPowerProfileMonitor:
  66  *
  67  * #GPowerProfileMonitor monitors system power profile and notifies on
  68  * changes.
  69  *
  70  * Since: 2.70
  71  */
  72
  73 /**
  74  * GPowerProfileMonitorInterface:
  75  * @g_iface: The parent interface.
  76  *
  77  * The virtual function table for #GPowerProfileMonitor.
  78  *
  79  * Since: 2.70
  80  */
  81
  82 G_DEFINE_INTERFACE_WITH_CODE (GPowerProfileMonitor, g_power_profile_monitor, G_TYPE_OBJECT,
  83                               g_type_interface_add_prerequisite (g_define_type_id, G_TYPE_INITABLE))
  84
  85
  86 /**
  87  * g_power_profile_monitor_dup_default:
  88  *
  89  * Gets a reference to the default #GPowerProfileMonitor for the system.
  90  *
  91  * Returns: (not nullable) (transfer full): a new reference to the default #GPowerProfileMonitor
  92  *
  93  * Since: 2.70
  94  */
  95 GPowerProfileMonitor *
  96 g_power_profile_monitor_dup_default (void)
  97 {
  98   return g_object_ref (_g_io_module_get_default (G_POWER_PROFILE_MONITOR_EXTENSION_POINT_NAME,
  99                                                  "GIO_USE_POWER_PROFILE_MONITOR",
 100                                                  NULL));
 101 }
 102
 103 /**
 104  * g_power_profile_monitor_get_power_saver_enabled:
 105  * @monitor: a #GPowerProfileMonitor
 106  *
 107  * Gets whether the system is in “Power Saver” mode.
 108  *
 109  * You are expected to listen to the
 110  * #GPowerProfileMonitor::notify::power-saver-enabled signal to know when the profile has
 111  * changed.
 112  *
 113  * Returns: Whether the system is in “Power Saver” mode.
 114  *
 115  * Since: 2.70
 116  */
 117 gboolean
 118 g_power_profile_monitor_get_power_saver_enabled (GPowerProfileMonitor *monitor)
 119 {
 120   gboolean enabled;
 121   g_object_get (monitor, "power-saver-enabled", &enabled, NULL);
 122   return enabled;
 123 }
 124
 125 static void
 126 g_power_profile_monitor_default_init (GPowerProfileMonitorInterface *iface)
 127 {
 128   /**
 129    * GPowerProfileMonitor:power-saver-enabled:
 130    *
 131    * Whether “Power Saver” mode is enabled on the system.
 132    *
 133    * Since: 2.70
 134    */
 135   g_object_interface_install_property (iface,
 136                                        g_param_spec_boolean ("power-saver-enabled",
 137                                                              "power-saver-enabled",
 138                                                              "Power Saver Enabled",
 139                                                              FALSE,
 140                                                              G_PARAM_READABLE | G_PARAM_STATIC_STRINGS | G_PARAM_EXPLICIT_NOTIFY));
 141 }