libkeepalive
Loading...
Searching...
No Matches
keepalive-backgroundactivity.h File Reference

Provides API for preventing / waking up from suspend. More...

#include <stdbool.h>

Go to the source code of this file.

Typedefs

typedef struct background_activity_t background_activity_t
 
typedef void(* background_activity_event_fn) (background_activity_t *activity, void *user_data)
 
typedef void(* background_activity_free_fn) (void *)
 

Enumerations

enum  background_activity_frequency_t {
  BACKGROUND_ACTIVITY_FREQUENCY_RANGE = 0 , BACKGROUND_ACTIVITY_FREQUENCY_THIRTY_SECONDS = 30 , BACKGROUND_ACTIVITY_FREQUENCY_TWO_AND_HALF_MINUTES = 30 + 2 * 60 , BACKGROUND_ACTIVITY_FREQUENCY_FIVE_MINUTES = 5 * 60 ,
  BACKGROUND_ACTIVITY_FREQUENCY_TEN_MINUTES = 10 * 60 , BACKGROUND_ACTIVITY_FREQUENCY_FIFTEEN_MINUTES = 15 * 60 , BACKGROUND_ACTIVITY_FREQUENCY_THIRTY_MINUTES = 30 * 60 , BACKGROUND_ACTIVITY_FREQUENCY_ONE_HOUR = 1 * 60 * 60 ,
  BACKGROUND_ACTIVITY_FREQUENCY_TWO_HOURS = 2 * 60 * 60 , BACKGROUND_ACTIVITY_FREQUENCY_FOUR_HOURS = 4 * 60 * 60 , BACKGROUND_ACTIVITY_FREQUENCY_EIGHT_HOURS = 8 * 60 * 60 , BACKGROUND_ACTIVITY_FREQUENCY_TEN_HOURS = 10 * 60 * 60 ,
  BACKGROUND_ACTIVITY_FREQUENCY_TWELVE_HOURS = 12 * 60 * 60 , BACKGROUND_ACTIVITY_FREQUENCY_TWENTY_FOUR_HOURS = 24 * 60 * 60 , BACKGROUND_ACTIVITY_FREQUENCY_MAXIMUM_FREQUENCY = 0x7fffffff
}
 

Functions

background_activity_tbackground_activity_new (void)
 
background_activity_tbackground_activity_ref (background_activity_t *self)
 
void background_activity_unref (background_activity_t *self)
 
void background_activity_set_wakeup_slot (background_activity_t *self, background_activity_frequency_t slot)
 
background_activity_frequency_t background_activity_get_wakeup_slot (background_activity_t *self)
 
void background_activity_set_wakeup_range (background_activity_t *self, int range_lo, int range_hi)
 
void background_activity_get_wakeup_range (background_activity_t *self, int *range_lo, int *range_hi)
 
bool background_activity_is_stopped (background_activity_t *self)
 
bool background_activity_is_waiting (background_activity_t *self)
 
bool background_activity_is_running (background_activity_t *self)
 
void background_activity_wait (background_activity_t *self)
 
void background_activity_run (background_activity_t *self)
 
void background_activity_stop (background_activity_t *self)
 
const char * background_activity_get_id (const background_activity_t *self)
 
void background_activity_set_user_data (background_activity_t *self, void *user_data, background_activity_free_fn free_cb)
 
void * background_activity_get_user_data (background_activity_t *self)
 
void background_activity_free_user_data (background_activity_t *self)
 
void * background_activity_steal_user_data (background_activity_t *self)
 
void background_activity_set_running_callback (background_activity_t *self, background_activity_event_fn cb)
 
void background_activity_set_waiting_callback (background_activity_t *self, background_activity_event_fn cb)
 
void background_activity_set_stopped_callback (background_activity_t *self, background_activity_event_fn cb)
 

Detailed Description

Provides API for preventing / waking up from suspend.

Typedef Documentation

◆ background_activity_t

Opaque background activity object

Allocate via background_activity_new() and release via background_activity_unref().

◆ background_activity_event_fn

typedef void(* background_activity_event_fn) (background_activity_t *activity, void *user_data)

Background activity notification function type

Parameters
activitybackground activity object pointer
user_datadata pointer set via background_activity_set_user_data()

◆ background_activity_free_fn

typedef void(* background_activity_free_fn) (void *)

User data free function type

Called when background activity object is deleted after the final reference is dropped via background_activity_unref(), or when background_activity_set_user_data() is called while user_data is already set.

Parameters
user_dataas set via background_activity_set_notify()

Enumeration Type Documentation

◆ background_activity_frequency_t

Enumeration of global wakeup slots for background activity objects

The value is actually just an integer number of seconds - but using one of the predefined values (or integer multiples of one) makes it more likely that multiple wakeups can be handled at the same time.

Enumerator
BACKGROUND_ACTIVITY_FREQUENCY_RANGE 

Delay range is used instead of global wakeup slot, see background_activity_get_wakeup_range().

BACKGROUND_ACTIVITY_FREQUENCY_THIRTY_SECONDS 

Wakeup at the next 30 second global slot

BACKGROUND_ACTIVITY_FREQUENCY_TWO_AND_HALF_MINUTES 

Wakeup at the next 2.5 minute global slot

BACKGROUND_ACTIVITY_FREQUENCY_FIVE_MINUTES 

Wakeup at the next 5 minute global slot

BACKGROUND_ACTIVITY_FREQUENCY_TEN_MINUTES 

Wakeup at the next 10 minute global slot

BACKGROUND_ACTIVITY_FREQUENCY_FIFTEEN_MINUTES 

Wakeup at the next 15 minute global slot

BACKGROUND_ACTIVITY_FREQUENCY_THIRTY_MINUTES 

Wakeup at the next 30 minute global slot

BACKGROUND_ACTIVITY_FREQUENCY_ONE_HOUR 

Wakeup at the next 1 hour global slot

BACKGROUND_ACTIVITY_FREQUENCY_TWO_HOURS 

Wakeup at the next 2 hour global slot

BACKGROUND_ACTIVITY_FREQUENCY_FOUR_HOURS 

Wakeup at the next 4 hour global slot

BACKGROUND_ACTIVITY_FREQUENCY_EIGHT_HOURS 

Wakeup at the next 8 hour global slot

BACKGROUND_ACTIVITY_FREQUENCY_TEN_HOURS 

Wakeup at the next 10 hour global slot

BACKGROUND_ACTIVITY_FREQUENCY_TWELVE_HOURS 

Wakeup at the next 12 hour global slot

BACKGROUND_ACTIVITY_FREQUENCY_TWENTY_FOUR_HOURS 

Wakeup at the next 24 hour global slot

BACKGROUND_ACTIVITY_FREQUENCY_MAXIMUM_FREQUENCY 

Maximum value that can be used

Function Documentation

◆ background_activity_new()

background_activity_t * background_activity_new ( void )

Create background activity object

Initially has reference count of 1.

Use background_activity_ref() to increment reference count and background_activity_unref() to decrement reference count.

Will be automatically released after reference count drops to zero.

Returns
pointer to background activity object, or NULL
Examples
periodic-wakeup.c.

◆ background_activity_ref()

background_activity_t * background_activity_ref ( background_activity_t * self)

Increment reference count of background activity object

Passing NULL object is explicitly allowed and does nothing.

Parameters
selfbackground activity object pointer
Returns
pointer to background activity object, or NULL in case of errors

◆ background_activity_unref()

void background_activity_unref ( background_activity_t * self)

Decrement reference count of background activity object

Passing NULL object is explicitly allowed and does nothing.

The object will be released if reference count reaches zero.

Parameters
selfbackground activity object pointer
Examples
periodic-wakeup.c.

◆ background_activity_set_wakeup_slot()

void background_activity_set_wakeup_slot ( background_activity_t * self,
background_activity_frequency_t slot )

Set global wakeup slot for background activity object

Global wakeup slot is defined as the next time in the future when some monotonic clock source has full seconds that is multiple of the given amount of seconds.

So every process that is using 10 minute slot is woken up simultaneously. And processes that are using 5 minute slots wake up simultaneously with the 10 minute wakeups and once in between the 10 minute slots.

Note that the 1st wakeup can occur anything from zero to specified amount of time.

SLOT |0.........1.........2.........3.........4.........5
|012345678901234567890123456789012345678901234567890 -> time
|
2 | x x x x x x x x x x x x x x x x x x x x x x x x x
5 | x x x x x x x x x x
10 | x x x x x
Parameters
selfbackground activity object pointer
slotseconds
See also
background_activity_set_wakeup_range()
Examples
periodic-wakeup.c.

◆ background_activity_get_wakeup_slot()

background_activity_frequency_t background_activity_get_wakeup_slot ( background_activity_t * self)

Get global wakeup slot used by background activity object

Parameters
selfbackground activity object pointer
Returns
seconds, or BACKGROUND_ACTIVITY_FREQUENCY_RANGE if ranged wakeup rather than global wakeup slot is used.

◆ background_activity_set_wakeup_range()

void background_activity_set_wakeup_range ( background_activity_t * self,
int range_lo,
int range_hi )

Set wakeup range for background activity object

The IPHB daemon (or DSME IPHB plugin nowadays) tries to minimize the amount of wakeups by maximizing the amount of processes that are woken up simultaneously.

For this purpose the wakeup range should be as wide as logically makes sense for the requesting client, but note that server side logic does not necessarily take the values as is. If range_lo is really small compared to range_hi, it will be scaled up to avoid seemingly premature wake ups.

As a rule of the thumb range_lo should be >= range_hi * 75% and range_hi - range_lo >= heartbeat delay (= hw watchdog kick period, for historical reasons 12 seconds).

If negative range_hi is used, wakeup range is adjusted to have the same length as heartbeat delay.

Parameters
selfbackground activity object pointer
range_lominimum sleep time in seconds
range_himaximum sleep time in seconds, or -1
See also
background_activity_set_wakeup_slot()

◆ background_activity_get_wakeup_range()

void background_activity_get_wakeup_range ( background_activity_t * self,
int * range_lo,
int * range_hi )

Get wakeup range used by background activity object

If global wakeup slot is used, the same value is returned for both range_lo and range_hi.

Parameters
selfbackground activity object pointer
range_lo[output] minimum sleep time in seconds
range_hi[output] maximum sleep time in seconds

◆ background_activity_is_stopped()

bool background_activity_is_stopped ( background_activity_t * self)

Check if background activity object is in stopped state

Stopped state means the object is not waiting for IPHB wakeup to occur and is not blocking device from suspending.

Parameters
selfbackground activity object pointer
Returns
true if object is in stopped state, false otherwise

◆ background_activity_is_waiting()

bool background_activity_is_waiting ( background_activity_t * self)

Check if background activity object is in waiting state

Waiting state means the object is waiting for IPHB wakeup to occur.

Parameters
selfbackground activity object pointer
Returns
true if object is in waiting state, false otherwise

◆ background_activity_is_running()

bool background_activity_is_running ( background_activity_t * self)

Check if background activity object is in running state

Waiting state means the object is blocking the device from entering suspend.

Parameters
selfbackground activity object pointer
Returns
true if object is in running state, false otherwise

◆ background_activity_wait()

void background_activity_wait ( background_activity_t * self)

Set background activity object to waiting state

IPHB wakeup slot or range is programmed. Automatic transition to running state is made when wakeup occurs.

Parameters
selfbackground activity object pointer
Examples
periodic-wakeup.c.

◆ background_activity_run()

void background_activity_run ( background_activity_t * self)

Set background activity object to running state

CPU-keepalive session is started and device is blocked from suspending. Application code MUST terminate running state as soon as possible by calling:

background_activity_wait() -> schedule next wakeup background_activity_stop() -> end keepalive session

Parameters
selfbackground activity object pointer

◆ background_activity_stop()

void background_activity_stop ( background_activity_t * self)

Set background activity object to running state

Active CPU-keepalive session is stopped / IPHB wakeup canceled.

Parameters
selfbackground activity object pointer
Examples
periodic-wakeup.c.

◆ background_activity_get_id()

const char * background_activity_get_id ( const background_activity_t * self)

Get client id used for CPU-keepalive D-Bus IPC

Every CPU-keepalive session needs to have unique within process id string. This function returns the id string associated with the background activity object.

Parameters
selfbackground activity object pointer
Returns
id string

◆ background_activity_set_user_data()

void background_activity_set_user_data ( background_activity_t * self,
void * user_data,
background_activity_free_fn free_cb )

Set user_data argument to be passed to notification callbacks

If non-null free_cb is specified, the user_data given is released by it when a) the background activity object is deleted b) user data is updated via another background_activity_set_user_data() call.

Parameters
selfbackground activity object pointer
user_datadata pointer
free_cbdata free callback
Examples
periodic-wakeup.c.

◆ background_activity_get_user_data()

void * background_activity_get_user_data ( background_activity_t * self)

Get user_data argument be passed to notification callbacks

Parameters
selfbackground activity object pointer
Returns
pointer set via background_activity_set_user_data()

◆ background_activity_free_user_data()

void background_activity_free_user_data ( background_activity_t * self)

Clear and free user_data that would be passed to notification callbacks

Parameters
selfbackground activity object pointer

◆ background_activity_steal_user_data()

void * background_activity_steal_user_data ( background_activity_t * self)

Detach user_data from background activity object without freeing it

Normally user data attached to background activity objects is released when object is deleted or replaced by new user data. If this is not desirable for some reason, the user data can be detached from object via background_activity_steal_user_data().

The caller must release the returned data as appropriate when it is no longer needed.

Parameters
selfbackground activity object pointer
Returns
pointer previously set via background_activity_set_user_data()

◆ background_activity_set_running_callback()

void background_activity_set_running_callback ( background_activity_t * self,
background_activity_event_fn cb )

Set notification function to be called on running state

When background activity object makes transition to running state the specified notification function is called.

NOTE: In order not to block suspend forever, the execution chain started by the callback function MUST end with call to either background_activity_wait() or background_activity_stop().

Parameters
selfbackground activity object pointer
cbcallback function pointer, or NULL
Examples
periodic-wakeup.c.

◆ background_activity_set_waiting_callback()

void background_activity_set_waiting_callback ( background_activity_t * self,
background_activity_event_fn cb )

Set notification function to be called on waiting state

When background activity object makes transition to waiting state the specified notification function is called.

Parameters
selfbackground activity object pointer
cbcallback function pointer, or NULL
Examples
periodic-wakeup.c.

◆ background_activity_set_stopped_callback()

void background_activity_set_stopped_callback ( background_activity_t * self,
background_activity_event_fn cb )

Set notification function to be called on stopped state

When background activity object makes transition to stopped state the specified notification function is called.

Parameters
selfbackground activity object pointer
cbcallback function pointer, or NULL
Examples
periodic-wakeup.c.