Source Annotation Language (SAL)

[brazi...@gmail.com]

SAL is a Microsoft thing. It's useful, in fact, with the right tools,
it's darn useful. If the source code for both sides of an interface is
available to a compiler, it's ability to develop and test assumptions
about the code is rather limited without something like SAL.

The combination of SAL and the static analysis tools really does pick
out all sorts of mischief. For those who remember, lint also looked at
certain keywords (e.g., FALLTHROUGH) in comments for information about
codepath assumptions. SAL is a more-developed version of that.

It adds information to an interface that would otherwise be difficult
or impossible for the compiler to determine from digesting the code. It
helps to associate buffer pointers with their sizes, lengths.

But, at the moment, it's only available on Visual Studio 2005, and the
analysis component that would make capitalize on the value of SAL is
only available on the 'Team Developer' edition -- not exactly something
that is widely available. It also makes the function prototypes more
more difficult to read.

One of the downsides of SAL is that it forces a certain kind of
function definition, and it adds parameters. As an example, take a look
at:

size_t mux_ltoa(long val, char *buf);

mux_ltoa() converts the number in 'val' to a string starting at buf. It
returns the length of resulting string. SAL would pretty much force
this to change to something like:

void mux_ltoa(long, __out_ecount_z(buf_max, buf_len) char *buf,
size_t buf_max, __out size_t *buf_len);

That is, the caller provides the buffer of size buf_max and mux_ltoa()
returns a zero-terminated string of length buf_len.

This alteration of the function prototype is not without risks -- more
parameters means more chances of getting it wrong, and out parameters
complicate the interaction between the caller's data and the callee's
data -- think multi-threaded code where the caller uses a pointer to
something global or in the heap that can be seen by another thread.

Also, for this project, both sides of an interface are available to
many different compilers -- all of which have a slightly different set
of linting. The combination of all those warnings from all those
compilers already provides something close to SAL.

So, I guess, my point is that I've looked it. It's too new, not widely
available, all our source is available to a compiler so we aren't
limited in the way SAL assumes, it would cause many prototypes to
change -- which adds risks, and oh BTW, SAL is still changing. So, I'm
deciding against using it for TinyMUX.

Brazil

[brazi...@gmail.com]

Instead of

"If the source code for both sides of an interface is available to a
compiler, it's ability to develop and test assumptions about the code
is rather limited without something like SAL."

It should have read

"Unless the source code for both sides of an interface is available to
a compiler, its ability to develop and test assumptions is rather

[brazi...@gmail.com]

It turns out that VS 2005 supports two schemes -- neither of which are
fully there. One is based on __declspec (#include <sal.h>), and the
other is based on an annotation syntax:

#include <CodeAnalysis/SourceAnnotations.h>
using namespace vc_attributes;

I know this stuff helps to enforce an interface contract, and the
compiler holds boths side of the interface to the same contract. For a
large body of code, this kind of tool is essential. But, it seems like
too much work (particularly with the SourceAnnotations.h approach) to
gloss over the differences between compilers while gaining enough
incremental benefit not obtained from any other method.

The Intel compiler (to drive its optimizations) does a surprising
amount of global code analysis. It still seems best to wait until at
least one of the schemes in VS 2005 is fully baked.

[Brazil]

The MSDN articles for this have settled somewhat. It isn't that hard
to gloss over the differences. However, the benefit of this is still
the same. One needs a large code base which is built in several,
independent compilation steps. Most compilers that do whole-program
optimizations have already looked at all the code and have already
found most of the problems.

Still, it isn't that hard to start doing, modules are separately
compilation, and there are some interest in sharing a set of utility
functions across module (at the link level) and codebases (if only at
the source level).

At the moment, all the SAL additions are only in the dev_brazil
branch. We should probably decide if we really want to do this before
I promote those changes to the dev branch.


Brazil