ArduinoMania

One of our favorite nuances of the C programming language (and its descendants) is the static keyword. It’s a little bit tricky to get your head around at first, because it can have two (or three) subtly different applications in different situations, but it’s so useful that it’s worth taking the time to get to know.

And before you Arduino users out there click away, static variables solve a couple of common problems that occur in Arduino programming. Take this test to see if it matters to you: will the following Arduino snippet ever print out “Hello World”?

void loop()
{
	int count=0;
	count = count + 1;
	if (count > 10) {
		Serial.println("Hello World");
	}
}

If you said, “Yes” you absolutely need to read this article. If you said “No, you need to define count as a global variable outside of the loop(), silly!”, you got the answer right in principle, but defining the variable as static is yet better. And we’ll see why.

But the shortest possible summary of this article is the following: if you want a variable to retain its value between calls to the function that contains it, declare that variable static.

And the summary rationale is that declaring a variable to be static sets the scope to be local, but makes the variable stick around for the lifetime of the program, rather than just the function call in which it was defined. Which means that it’s not re-initialized on every call to the function, and that lets us effectively store data within a function. It’s a great trick to have in your programmers’ toolbag.

Scope and Duration

To understand static, we’ll have to tease apart two related concepts of a variable’s availability to our code: scope and duration (or lifetime).

Most of you will know about variable scope. In many languages, if you declare a variable within a function or block, it stays inside that function or block. That’s called “local scope” or “function scope” or similar. Other functions can’t use that variable without our function explicitly passing the variable out. This is great, because it means that you can name all your counter variables count and they won’t collide with each other across functions. You probably know this.

Variables in C & Co. also have a lifetime that they’re guaranteed to be available for, also called their “duration”. After their duration is up, you won’t be able to use the variable any more. This is closely related to the idea of “scope” which specifies in which functional blocks of code the variable is available, but you’re going to want to keep them separate in your mind. Easiest is to think of duration as being a time, and scope as being a location (in code-space).

The default duration of a variable is the current call of the function. That’s why something like:

int counter (void)
{
	int count=0;
	count=count+1;
	return count;
}

will always return 1. Each time you call the function, count gets re-initialized to zero, and when the function returns, that variable’s storage gets reallocated because it has function duration. (And this is exactly the problem with the Arduino snippet above.)

We want our counter() function to keep track of how many times it’s been called. We need the variable count to have program duration — it needs to stick around as long as our code is running, and not get reallocated after every function call.

Globals?

The brute-force method is to declare count as a global variable by defining it outside of any functions. Global variables live for the duration of the program, so the value contained in count will stay available. So far, so good. But variables with global scope have the side effect of making count available from any other function. Sometimes this is exactly what we want, but a lot of the time it’s not.

The problem with global scope is that you can’t use any other global variables of the same name, so you need pick the names carefully to be unique so that they don’t clash. This isn’t a huge problem if you just use long, specific names: My_Global_Loop_Counter instead of count, for instance.

A more subtle problem arises when you intend to use another variable named count in a second function, but forget to declare it. The second function thinks that you meant to use the globally defined count, and havoc ensues.

Finally, it’s tempting to use global variables to pass data among different functions. (This is especially true for people who haven’t yet made peace with pointers and structures.) If you spread the functions using a global variable across different files, it can take heroic feats of debugging to track down every location where a popular global variable is accessed or modified. That is to say, global variables can lead to fragmented, hard to debug code.

No, Static.

Anyway, if you buy the arguments above, what you really want is a variable with program duration but function scope. And that’s exactly what static does when it’s applied to a variable inside a function. The language has precisely the feature you want, so you might as well use it.

And to bring it on home, the Arduino snippet up above will work just fine with a globally defined count variable,

int count;
void loop()
{
	count = count + 1;
	if (count > 10) {
		Serial.println("Hello World");
	}
}

but it’s also a lot cleaner when written using static:

void loop()
{
	static int count;
	count = count + 1;
	if (count > 10) {
		Serial.println("Hello World");
	}
}

because the name “count” isn’t globally exposed. It’s also declared in the function that uses it, so there’s no question of to whom it belongs. And it works. You can’t beat that.

Static and global variables (all variables with program duration) are pre-initialized to zero by default, so we didn’t need to write static int count = 0; above. However, if we wanted the initial value to be non-zero, we could define the variable like so: static int count = 42;.

There’s something creepy about static int count = 42;, though. It looks like we’re declaring the variable and then setting its value on every pass through the code. But the static keyword prevents this. Trust us, or modify the demo code above to test it out for yourself.

Data Hiding and Singletons and Stuff

There’s a second, related, use of static to mention. When used outside of any functions, at the top-level of a file, static limits the scope to the file in question. Contrast this with global variables which have truly global scope and thus are available across files. Static variables defined outside of functions, then, are like a quasi-global variable: available for the duration of the program from every function defined within the file, but not reachable from outside the file.

Here’s an example where this quasi-global functionality is useful. Say we’d like to spin off the counter code into a counter library. We’re starting off with something like this:

int counter(void){
	static int count;
	count++;
	return count;
}

Every time you call counter() from other code, the function keeps the old value of count, adds one to it, and the counter behaves like it should. This is the function-scope static definition.

But now imagine that we’d also like to reset the counter. We might want a reset() function that will set the value back to zero. But count has function scope, so our reset() function won’t be able to touch it. The solution here is to use the static type declaration at file scope.

You could have something like this in your file “counter.c”:

static int count;

int counter(void){
	count++;
	return count;
}

void reset_count(void){
	count = 0;
}

static void my_secret_function(void){
	count = 42;
}

Because count is defined static at file scope, all the functions in the file will be able to use it, and the value will persist between function calls. Additionally, because my_secret_function() is defined static, it’s not callable from outside this file, though functions defined here can call it as usual.

Defining variables (and functions) static at file scope is perfect for storing library-specific stuff that is needed for the library, but that doesn’t need to be seen on the outside. This is a lot like what object-oriented languages do with public and private data and methods.

In contrast to the object-oriented pattern, though, we’ve only got one instance of our data. You can’t create a second one easily. This is what the software engineer types call a singleton.  These singletons are great for keeping track of global state, where you just write some simple functions to modify and access the data. Since the data is static and file-local, you know that you can’t mess it up from outside, and the manipulation functions are available anywhere you can #include them.

The drawback of singletons are that there’s only ever one of them. If you wanted two counters, for instance, this code wouldn’t help. When you get to such cases, you’ll want full-blown object-oriented support.

… and Arduino

This was a lot of heavy C theory, so you might think it’s not applicable if you’re programming in Arduino. If you think like that, you weren’t paying attention during the last “Embed”; Arduino is C/C++ with added convenience libraries. And in fact, the particular way that Arduino repeatedly calls the loop() function makes knowing a bit about scoping nearly mandatory: all of your function-call-duration variables get wiped each time through the loop unless you do something.

As we saw in the introductory example, you can’t initialize a variable inside the loop() without it resetting each time through the loop. If you didn’t know about the static keyword, you’d probably take the brute-force solution and define the variable as global. A bunch of the Arduino examples do just this.

What could go wrong?

int i;

void loop(){
	i++;
	Serial.println(i);
	delay(100);
	doSomethingTwice();
}

void doSomethingTwice(){
	for (i=0; i<2; i++){
		Serial.println("twice?");
	}
}

Well, say you’ve gotten in the habit, as we have, of using i as a generic loop variable. And say you re-used it without definition in another function, maybe even in another “.ino” file, that you call from within the loop. Because i is a global variable, the accidental second use is actually perfectly kosher. The compiler won’t be able to help you find the mistake, but your program won’t work right. Instead of counting up, the poor Arduino will just keep printing “3”.

There are two causes of this problem: forgetting to declare i inside doSomethingTwice(), and creating a global variable with an easy-to-reuse name. You will forget to declare variables from time to time. We all do. And when we do, we want the compiler to let us know.

So there are two ways to avoid the problem. The first solution is to name your global variables something crazy so that they’re unlikely to be reused. “My_Amazing_Global_Loop_Counter” would work well. Even typing it once makes me never want to type it again.

The “right” solution solves the initial problem that led us to use a global variable in the first place. We simply define our counter variable as static inside loop() and then it has program duration but function scope and all’s well. Now we can even call the counter variable i with impunity, because it’s scoped to loop().

void loop(){
	static int i;
	i++;
	Serial.println(i);
	delay(100);
	doSomethingTwice();
}

void doSomethingTwice(){
	// You'll get an error here b/c i isn't declared.  Thanks, compiler!
	for (i=0; i<2; i++){
		Serial.println("twice?");
	}
}

And what do you do if you want to share variables among different functions within a single “sketch”? One way is to pass them directly as arguments, but again you’ll see lots of folks resort to global variables that can be simply accessed from each relevant function. It’s not a huge problem if you take care to name the variables well, so we won’t insist.

But you could also do it “correctly” and define the global variables as static at the file level instead. You’ll still be able to make subtle mistakes within your own functions, but by declaring the variables static you won’t run the chance of confusing them up with variables defined elsewhere in the Arduino infrastructure. It’s a belt when you’re already wearing suspenders, but it doesn’t cost you anything except a tiny bit more typing.

Conclusion

Use the static keyword for variables within a function when you want the value to persist across function calls, but you don’t need to enlarge the scope. Use the static keyword for functions and variables at the file level when you want them to behave like quasi-globals, being accessible everywhere within the file but hidden from the outside.

See? That’s not so mysterious after all.