com.twofortyfouram.spackle.power

Class PartialWakeLock

java.lang.Object

com.twofortyfouram.spackle.power.PartialWakeLock

@ThreadSafe
public final class PartialWakeLock
extends Object

Manages partial WakeLocks.

Users of this class must have the permission Manifest.permission.WAKE_LOCK.

Method Summary

Modifier and Type	Method and Description
void	acquireLock() Acquire a partial WakeLock.
void	acquireLockIfNotHeld() Similar to acquireLock(), but only acquires a lock if isHeld() returns false.
static Map<String,Long>	dumpWakeLockUsage() Dumps cumulative WakeLock usage from this class and PartialWakeLockForService.
boolean	isHeld() Determine whether a WakeLock is held.
static PartialWakeLock	newInstance(Context context, String lockName, boolean isReferenceCounted) Constructs a new PartialWakeLock.
void	releaseLock() Release a WakeLock previously acquired.
void	releaseLockIfHeld() Like releaseLock() but only releases if isHeld() returns true.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

dumpWakeLockUsage

public static Map<String,Long> dumpWakeLockUsage()

Dumps cumulative WakeLock usage from this class and PartialWakeLockForService. This is useful to debug WakeLock usage.

Returns:

A map of WakeLock name and cumulative duration in milliseconds that the lock was held.

newInstance

public static PartialWakeLock newInstance(Context context,
                                          String lockName,
                                          boolean isReferenceCounted)

Constructs a new PartialWakeLock.

It is recommended that applications use a finite number of values for lockName, as an unbounded number of names would create a memory leak. For example, consider a background service. Using the name "my_service_lock" every time the service is started would be better than "my_service_lock_%d" where %d is incremented every time the service starts. Internally this class maintains a historical count of lock durations to enable dumpWakeLockUsage(), so creating an unbounded number of tags would grow linearly in memory usage.

Parameters:

context - Application context.

lockName - a tag for identifying the lock.

isReferenceCounted - true if the lock is reference counted. False if the lock is not reference counted.

Returns:

A new PartialWakeLock.

acquireLock

public void acquireLock()

Acquire a partial WakeLock.

This method may be called multiple times. If the lock is reference counted, then each call to this method needs to be balanced by a call to releaseLock(). Otherwise if the lock is not reference counted, then multiple calls have no effect.

acquireLockIfNotHeld

public void acquireLockIfNotHeld()

Similar to acquireLock(), but only acquires a lock if isHeld() returns false.

releaseLock

public void releaseLock()

Release a WakeLock previously acquired. This method should balance a call to acquireLock().

Throws:

IllegalStateException - if the WakeLockManager is underlocked.

releaseLockIfHeld

public void releaseLockIfHeld()

Like releaseLock() but only releases if isHeld() returns true. This method will not throw exceptions for being underlocked.

isHeld

public boolean isHeld()

Determine whether a WakeLock is held.

Returns:

true if a lock is held. Otherwise returns false.

toString

public String toString()

Overrides:

toString in class Object