jdk.dio.power

Interface PowerManaged

public interface PowerManaged

The PowerManaged interface provides methods that a Device class may implement to control how the underlying device hardware resource is managed by the power management facility of the device.

The power management states defined are device as well as host device-dependent. For devices on a microcontroller unit, there may be no distinction between POWER_OFF, LOW_POWER and LOWEST_POWER and they may for example all be supported by clock-gating the unused devices. Conversely, a device external to the host device could support the four power management modes and could especially be powered off.

A power state change may be dictated by the power management facility of the device or it may be requested by the power management facility on behalf of the application itself or of another application (see requestPowerStateChange). A power state change for a specific device may be requested by another application if the device or some of the underlying device hardware resources are shared. This is, for example, the case on a GPIOPin instance: another application may have opened a different GPIO pin controlled by the same GPIO controller; the application will get notified of any power state changes requested by the other application. Devices currently open by an application whose power managements are logically or physically dependent belong to the same power management group (see PowerManaged.Group).

An application may register to get notified of power state changes. When notified, the application may take the following actions:

1. the application may save or restore the state/configuration of the device if needed. Saving the device's state/configuration may be needed when the application is being notified of a power state change requested by another application on a device hardware resources shared with the current application. Saving/Restoration of the device's state/configuration may be needed when changing from/to POWER_OFF or LOWEST_POWER to/from POWER_ON, as the device state/context may not be preserved.
2. the application may veto a power state change. For example, the application may veto a power state change from POWER_ON to LOWEST_POWER if the application is currently using or is about to use the designated device.
3. the application may grant a shorter power state change duration. For example, the application may grant a duration of a power state change from POWER_ON to LOWEST_POWER shorter than the specified duration if the application anticipates it will use the designated device earlier than the specified duration.

If application-dictated power saving for a device is not explicitly enabled by a call to one of the enablePowerSaving methods the default power saving strategy of the platform applies. This strategy is platform as well as implementation-dependent. It may define power saving rules (changing the power state of a device when certain conditions are met) that may or may not differ from device device to device. It may, for example, consist in forcefully changing all devices' power state to LOWEST_POWER upon some condition; in such a situation, attempting to access the device without restoring its state/configuration may result in unexpected behavior. Therefore an application should always either:

1. register for power state changes on the devices it uses
2. or, register for system-wide power state changes (if supported by the platform) and close the devices when going to power saving modes that may not preserve the device state/context and then open again the devices when returning from such power saving modes.

When an application has enabled application-dictated power saving for several devices that belong to the same power management group (by a call to one of the enablePowerSaving methods) the effective set of enabled power states is the intersection of the individually sets of enabled power states (bitwise AND). This corresponds to the power states enabled for the group. If one of the device is subsequently closed the power states enabled for the group MUST reflect the change.

Valid Power State Transitions

The valid power state transitions are as follows:

From the higher power states (lesser power saving states) to the lower power states (higher power saving states):

• from POWER_ON to LOW_POWER
• from POWER_ON to LOWEST_POWER
• from POWER_ON to POWER_OFF
• from LOW_POWER to LOWEST_POWER
• from LOW_POWER to POWER_OFF
• from LOWEST_POWER to POWER_OFF

From any of the lower power states (higher power saving state) back to the highest power state (lesser power saving state):

• from LOW_POWER to POWER_ON
• from LOWEST_POWER to POWER_ON
• from POWER_OFF to POWER_ON

Subsequently, after the duration of a power state change requested by a call to requestPowerStateChange has expired the device's power state always transitions to POWER_ON.

See Also:

PowerSavingHandler

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	PowerManaged.Group The Group interface provides methods for registering for power state changes of devices belonging to the same power management group.

Field Summary

Fields

Modifier and Type	Field and Description
static int	LOW_POWER Low power mode (may save less power while preserving more device context/state than LOWEST_POWER, hence allowing for a faster return to full performance).
static int	LOWEST_POWER Lowest power mode (may save more power while preserving less device context/state than LOW_POWER, hence only allowing for a slower return to full performance).
static int	POWER_OFF Power has been fully removed from the device (for example from an external device).
static int	POWER_ON Fully powered on.
static long	UNLIMITED_DURATION Unlimited or unknown power state change requested duration.

Method Summary

Methods

Modifier and Type	Method and Description
void	disablePowerSaving() Disables application-dictated power saving for the Device instance.
void	enablePowerSaving(int powerStates) Enables application-dictated power saving for the Device instance.
void	enablePowerSaving(int powerStates, PowerSavingHandler handler) Enables application-dictated power saving for the Device instance and registers a PowerSavingHandler instance to get asynchronously notified when the power management facility is about to change the power state of the Device instance, hence allowing the application to veto the power state change on the device.
PowerManaged.Group	getGroup() Returns the power management Group this device belongs to.
int	getPowerState() Returns the current power state of the Device instance.
long	requestPowerStateChange(int powerState, long duration) Requests the change of the device's current power state to the specified power state for the specified duration.

Field Detail

LOW_POWER

static final int LOW_POWER

Low power mode (may save less power while preserving more device context/state than LOWEST_POWER, hence allowing for a faster return to full performance).

When transitioning from this state to POWER_ON no state/configuration restoration of the device device must be needed.

This bit flag can be bitwise-combined (OR) with other power state bit flags.

See Also:

Constant Field Values

LOWEST_POWER

static final int LOWEST_POWER

Lowest power mode (may save more power while preserving less device context/state than LOW_POWER, hence only allowing for a slower return to full performance).

When transitioning from this state to POWER_ON some state/configuration restoration of the device device may be needed. This state/configuration restoration of the device may be handled by a PowerSavingHandler.

This bit flag can be bitwise-combined (OR) with other power state bit flags.

See Also:

Constant Field Values

POWER_OFF

static final int POWER_OFF

Power has been fully removed from the device (for example from an external device).

When transitioning from this state to POWER_ON a complete state/configuration restoration of the device may be needed. This state/configuration restoration of the device may be handled by a PowerSavingHandler.

This bit flag can be bitwise-combined (OR) with other power state bit flags.

See Also:

Constant Field Values

POWER_ON

static final int POWER_ON

Fully powered on.

This bit flag can be bitwise-combined (OR) with other power state bit flags.

See Also:

Constant Field Values

UNLIMITED_DURATION

static final long UNLIMITED_DURATION

Unlimited or unknown power state change requested duration.

See Also:

Constant Field Values

Method Detail

disablePowerSaving

void disablePowerSaving()
                        throws java.io.IOException,
                               ClosedDeviceException

Disables application-dictated power saving for the Device instance. The power saving strategy of the platform applies.

If a PowerSavingHandler instance was registered using enablePowerSaving(int, jdk.dio.power.PowerSavingHandler) it will be unregistered.

Throws:

ClosedDeviceException - if the device has been closed.

java.lang.SecurityException - if the caller does not have the required permission.

java.io.IOException - if some other I/O error occurs.

enablePowerSaving

void enablePowerSaving(int powerStates)
                       throws java.io.IOException,
                              ClosedDeviceException

Enables application-dictated power saving for the Device instance. Only the specified power states are enabled for the Device instance. Any attempt by another application to change the power state of the Device instance to a state different from those specified will be automatically vetoed. The power management facility will not forcefully change the power state of the Device instance to a state different from those specified unless in case of urgency.

By using the requestPowerStateChange method an application may override this directive and request a power state change to a state other than those specified.

Note that the POWER_ON state is always implicitly enabled.

Subsequent calls to this method silently override any previous settings of enabled power states as well as registered PowerSavingHandler.

Parameters:

powerStates - bitwise OR of enabled power states: LOW_POWER, LOWEST_POWER or POWER_OFF.

Throws:

java.lang.IllegalArgumentException - if powerStates is not a bitwise OR of the defined power state values.

java.lang.SecurityException - if the caller does not have the required permission.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

enablePowerSaving

void enablePowerSaving(int powerStates,
                     PowerSavingHandler handler)
                       throws java.io.IOException,
                              ClosedDeviceException

Enables application-dictated power saving for the Device instance and registers a PowerSavingHandler instance to get asynchronously notified when the power management facility is about to change the power state of the Device instance, hence allowing the application to veto the power state change on the device. Only the specified power states are enabled for the Device instance. Any attempt by another application to change the power state of the Device instance to a state different from those specified will be automatically vetoed. The power management facility will not forcefully change the power state of the Device instance to a state different from those specified unless in case of urgency.

By using the requestPowerStateChange method an application may override this directive and request a power state change to a state other than those specified.

Note that the POWER_ON state is always implicitly enabled.

Since only the specified power states are enabled, the application will only be notified of changes to these states (including the POWER_ON state).

Subsequent calls to this method silently override any previous settings of enabled power states as well as registered PowerSavingHandler.

Parameters:

powerStates - bitwise OR of enabled power states: LOW_POWER, LOWEST_POWER or POWER_OFF.

handler - the PowerSavingHandler instance to be notified when a power state change is requested or confirmed for the device.

Throws:

java.lang.IllegalArgumentException - if powerStates is not a bitwise OR of the defined power state values.

java.lang.SecurityException - if the caller does not have the required permission.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

getPowerState

int getPowerState()
                  throws java.io.IOException,
                         ClosedDeviceException

Returns the current power state of the Device instance. If application-dictated power saving is disabled (see disablePowerSaving the power state depends on the power saving strategy of the platform.

Returns:

the current power state of the Device instance: POWER_ON, LOW_POWER, LOWEST_POWER or POWER_OFF.

Throws:

java.lang.SecurityException - if the caller does not have the required permission.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

requestPowerStateChange

long requestPowerStateChange(int powerState,
                           long duration)
                             throws java.io.IOException,
                                    ClosedDeviceException

Requests the change of the device's current power state to the specified power state for the specified duration. The power state change may be vetoed by the system or by other applications, or the actual duration of the power state change may be lesser than the requested duration.

If a PowerSavingHandler instance has been registered by the current application, it will not get notified of the requested power state change (neither its request nor its confirmation); it will only get notified when returning back to the POWER_ON state or of any interleaving power state changes requested by the system or by other applications.

If the device is already in the requested power state no notification will be performed and the remaining duration of the current state will be set to the smallest of the requested duration and the currently remaining duration.

Any invalid power state request (see Valid Power State Transitions) is automatically vetoed and 0 is returned.

A transition to the POWER_ON state can never be vetoed such as to not deny device access to other applications and the duration parameter is ignored and always assumed to be UNLIMITED_DURATION.

Parameters:

powerState - the new power state of the Device instance: POWER_ON, LOW_POWER, LOWEST_POWER or POWER_OFF.

duration - the expected duration (in milliseconds) of the requested power state change or UNLIMITED_DURATION if unlimited or unknown.

Returns:

the actual (negotiated) duration (in milliseconds) - which may be lesser than or equal to the requested duration ( UNLIMITED_DURATION if an unlimited/unknown duration was requested) or 0 if the requested power state change has been vetoed.

Throws:

java.lang.IllegalArgumentException - if powerState is not one of the defined power state values or if duration is not greater than 0 or equal to UNLIMITED_DURATION.

java.lang.SecurityException - if the caller does not have the required permission.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

getGroup

PowerManaged.Group getGroup()
                            throws java.io.IOException,
                                   ClosedDeviceException

Returns the power management Group this device belongs to.

A compliant implementation MAY return the same Group instance (application-wise) upon subsequent calls to this PowerManaged Device instance or to other PowerManaged Device instances belonging to that same power management Group (until that Group is closed - see PowerManaged.Group).

Returns:

the Group this device belongs to.

Throws:

java.lang.SecurityException - if the caller does not have the required permission.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.