aboutsummaryrefslogtreecommitdiffstats
path: root/docs/source/lang/api/volatile.rst
blob: 276bb6a00a0e41323b0c282ccc7353758b827295 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
.. highlight:: cpp

.. _lang-volatile:

``volatile``
============

The ``volatile`` keyword known is a variable *qualifier*.  It is
usually used before the datatype of a variable, to modify the way in
which the compiler treats the variable.

Declaring a variable ``volatile`` is a directive to the compiler. The
compiler is software which translates your C++ code into the machine
code, which are the real instructions for the STM32 chip in the
Maple. (The particular compiler we provide for use with the Maple is a
version of :ref:`GCC <arm-gcc>`).

Specifically, it directs the compiler to read the variable's value
fresh every time it is used, rather than "backing up" the value and
reading from its backup copy. (Compilers often "back up" a variable's
value in RAM into a storage location called a *register*; this is done
for efficiency).

A variable should be declared ``volatile`` whenever its value can be
changed by something beyond the control of the code section in which
it appears, such as an :ref:`external interrupt
<external-interrupts>`. On the Maple, the only place that this is
likely to occur is in sections of code associated with interrupts.

Example
-------

::

    // toggles LED when interrupt pin changes state

    int pin = 13;
    volatile int state = LOW;

    void setup() {
      pinMode(pin, OUTPUT);
      attachInterrupt(0, blink, CHANGE);
    }

    void loop() {
      digitalWrite(pin, state);
    }

    void blink() {
      if (state == HIGH) {
        state = LOW;
      } else {
        // state must be HIGH
        state = HIGH;
      }
    }

See also
--------

- :ref:`External Interrupts <external-interrupts>`
- :ref:`lang-attachinterrupt`
- :ref:`lang-detachinterrupt`

.. include:: cc-attribution.txt