What vertical bar('|') means in android?

Question

For example:

WakeLock wakeLock = powerManager.newWakeLock(PowerManager.FULL_WAKE_LOCK|
        PowerManager.ACQUIRE_CAUSES_WAKEUP|PowerManager.ON_AFTER_RELEASE, "Alarm");

What does the ' | ' character mean?

---

More details about the problem:

I'm asking this because when I instantiate the wakelock with only PowerManager.AQUIRE_CAUSES_WAKEUP the program stops working, where as when I use the way above, it works fine.

I'm wondering if the cause of this is because the program ignore the ACQUIRE_CAUSES_WAKEUP tag and it ends up not being used.

Answer 1

In general, that symbol (|) is a bitwise OR. It's used in a lot of different languages and environments outside of Android.

It's usage is:

"X|Y : if X or Y is 1, then the result is 1"

In your specific case it's being used to create a bit field. Besure to review the Android power manager code base here.

Possible flags for this API are:

PARTIAL_WAKE_LOCK        = 0x01 
SCREEN_DIM_WAKE_LOCK     = 0x06
SCREEN_BRIGHT_WAKE_LOCK  = 0x0a
FULL_WAKE_LOCK           = 0x1a

These are mutually exclusive (you can only pick one), but you can "OR in" some other flags:

ON_AFTER_RELEASE         = 0x20000000
ACQUIRE_CAUSES_WAKEUP    = 0x10000000

So once your code runs it ORs these flags together resulting in:

    0x20000000
  | 0x10000000
  | 0x0000001a
---------------
    0x3000001a

---

I'm asking this because when i instantiate the wakelock with only "PowerManager.AQUIRE_CAUSES_WAKEUP" the program stops working

That's because you have to pick one of the levels of wake lock (PARTIAL, SCREEN_DIM, SCREEN_BRIGHT, or FULL), you're trying to run with just one of the optional wake lock flags...

Answer 2

The | is a bitwise or, and it goes beyond Android. It is often used to stuff multiple options into one parameter.

So a function of the form f(X|Y|Z) means the function should use options X, Y and Z. Of course, X, Y and Z should be appropriately coded to ensure | will preserve their values.

Answer 3

From the doc

bitwise inclusive OR => |

The Bitwise inclusive OR ( | ) operator performs the bitwise inclusive OR operation on each parallel pair of bits of two operands. In each pair, the result is 1, if either first or second bit is 1 (or both are 1). Otherwise the result is 0. Lets see the table of using inclusive operations. Lets understand the inclusive OR operations using truth table:

    (OR)

 A   B   Result
 0   0   0
 1   0   1
 0   1   1
 1   1   1

Answer 4

If you look at constants most often used with | in the type of example you've shown, their values are powers of 2. For example:

Options.OPTION1 = 1;
Options.OPTION2 = 2;
Options.OPTION3 = 4;
Options.OPTION4 = 8;

In binary (Note I have omitted the 0b prefix for ease of reading):

Options.OPTION1 = 0001;
Options.OPTION2 = 0010;
Options.OPTION3 = 0100;
Options.OPTION4 = 1000;

If you OR Options.OPTION1 and Options.OPTION3, the result is 0101;

Options.OPTION1 | Options.OPTION3 => 0101

This enables you to pack multiple values into one since each combination of options is unique.

You can "extract" the options from the packed value by ANDing the options:

packedValue = Options.OPTION1 | Options.OPTION3;


packedValue & Options.OPTION3 => true;
packedValue & Options.OPTION4 => false;

Since

0101 AND 0100 => 0100 => true

and

0101 AND 1000 => 0000 => false