that are ready or zero, in which case the call returned because the time-out was reached. With this simple change, the usability problems disappear and, because the caller no longer needs to copy the arguments, the code is far more efficient as well.

There are many other ways to fix the problems with Select() (such as the approach used by epoll()). The point of this example is not to come up with the ultimate version of Select(), but to demonstrate how a small number of minor oversights can quickly add up to create code that is messy, difficult to maintain, error prone, and inefficient. With a slightly better interface to Select(), none of the code I outlined here would be necessary, and I (and probably many other programmers) would have saved considerable time and effort.

figure 2: the doselect() function.

public void doSelect(List checkRead, List checkWrite,

List checkError, int milliseconds)

{

the cost of Poor aPis

The consequences of poor API design are numerous and serious. Poor APIs are difficult to program with and often require additional code to be written, as in the preceding example. If nothing else, this additional code makes programs larger and less efficient because each line of unnecessary code increases working set size and reduces CPU cache hits. Moreover, as in the preceding example, poor design can lead to inherently inefficient code by forcing unnecessary data copies. ( Another popular design flaw—namely, throwing exceptions for expected outcomes—also causes inefficiencies because catching and handling exceptions is almost always slower than testing a return value.)

The effects of poor APIs, however, go far beyond inefficient code: poor APIs are harder to understand and more difficult to work with than good ones. In other words, programmers take longer to write code against poor APIs than against good ones, so poor APIs directly lead to increased development cost. Poor APIs often require not only extra code, but also more complex code that provides more places where bugs can hide. The cost is increased testing effort and increased likelihood for bugs to go undetected until the software is deployed in the field, when the cost of fixing bugs is highest.

Much of software development

ArrayList readCopy; // Copies of the three parameters because ArrayList writeCopy; // Select() clobbers them.

ArrayList errorCopy; if (milliseconds <= 0) {

// Simulate waiting forever. do {

// Make copy of the three lists here...

Select(readCopy, writeCopy, errorCopy, Int32.MaxValue);

} while ((readCopy == null || readCopy.Count == 0) &&

(writeCopy == null || writeCopy.Count == 0) && (errorCopy == null || errorCopy.Count == 0));

} else {

// Deal with non-infinite timeouts. while ((milliseconds > Int32.MaxValue / 1000) &&

(readCopy == null || readCopy.Count == 0) &&

(writeCopy == null || writeCopy.Count == 0) &&

(errorCopy == null || errorCopy.Count == 0)) {

// Make a copy of the three lists here...

Select(readCopy, writeCopy, errorCopy,

( Int32.MaxValue / 1000) 1000); milliseconds -= Int32.MaxValue / 1000;

}

} if ((readCopy == null || readCopy.Count == 0) &&

(writeCopy == null || writeCopy.Count == 0) &&

(errorCopy == null || errorCopy == 0)) {

Select(checkRead, checkWrite, checkError, milliseconds*1000); }

// Copy the three lists back into the original parameters here...

}

 

is about creating abstractions, and APIs are the visible interfaces to these abstractions. Abstractions reduce complexity because they throw away irrelevant detail and retain only the information that is necessary for a particular job. Abstractions do not exist in isolation; rather, we layer abstractions on top of each other. Application code calls higher-level libraries that, in turn, are often implemented by calling on the services provided by lower-level libraries that, in turn, call on the services provided by the system call interface of an operating system. This hierarchy of abstraction layers is an immensely powerful and useful concept. Without it, software as we know it could not exist because programmers would be completely overwhelmed by complexity.

The lower in the abstraction hierarchy an API defect occurs, the more serious are the consequences. If I mis-design a function in my own code, the only person affected is me, because I am the only caller of the function. If I mis-design a function in one of our project libraries, potentially all of my

colleagues suffer. If I mis-design a function in a widely published library, potentially tens of thousands of programmers suffer.

Of course, end users also suffer. The suffering can take many forms, but the cumulative cost is invariably high. For example, if Microsoft Word contains a bug that causes it to crash occasionally because of a mis-designed API, thousands or hundreds of thousands of end users lose valuable time. Similarly, consider the numerous security holes in countless applications and system software that, ultimately, are caused by unsafe I/O and string manipulation functions in the standard C library (such as scanf() and strcpy()). The effects of these poorly designed APIs are still with us more than 30 years after they were created, and the cumulative cost of the design defects easily runs to many billions of dollars.

Perversely, layering of abstractions is often used to trivialize the impact of a bad API: “It doesn’t matter—we can just write a wrapper to hide the problems.” This argument could not be more wrong because it ignores the