AspectC++ Programming Guide

Every execution join point is associated with the fully qualified name of the respective function, such as Square::draw() in the aforementioned example. Pure virtual functions do not have any function body and, thus, do not provide execution join points either.

draw() execution join point

The call join point, however, typically occurs elsewhere in the program, that is, at those locations where the respective function is invoked. The following code snippet shows a call join point for the function draw():

int main() {
  Square s;
  s.draw();<== \pos{draw}
}

draw

Every call join point is associated with two fully qualified names: the name of the caller function and the name of the callee function. In the aforementioned code snippet, Square::draw() is the callee function and main() is the caller function. The name of the caller function can be used to select call join points within the main() function only, for example, and thus to filter out call join points elsewhere. Calls via functions pointers do not provide any call join point, as the name of the callee function cannot be determined at compile time.

draw() call join point

In contrast to execution join points, pure virtual functions do provide call join points. AspectC++ also supports call join points for callee functions defined in external program libraries that have not been compiled with AspectC++.

2.1.2 Constructor and Destructor

Join points for class constructors are much like execution join points for member functions. The construction join point is on the constructor body itself and covers all the statements within that constructor body. The following example shows the construction joint point for a user-defined constructor:

class Square {
  int length;
public:
  Square() : length(0)<== \pos{draw1}
  {<== \pos{draw2}
  }
};

member initializer list

The construction join point is located after the member initializer list; that is, the member initializer list is executed prior to the construction join point. Implicit default constructors and (implicit) copy constructors provide construction join points as well.

5cm

-1cm

construction join point

When a class instance is to be deleted eventually, the class destructor gets executed. The class destructor, either implicitly defined or user-defined as shown in the following code snippet, provides a destruction join point:

class Square {
  /* ... */
public:
  ~Square()
  {<== \pos{draw1}
  }
};

3cm

Both construction and destruction join points are on their respective constructor and destructor bodies. There is no call join point for constructors and destructors in AspectC++.

destruction join point

2.1.3 Variable Access

AspectC++ supports join points on read and write accesses to member variables and global variables. This means that there are no join points for local variables within functions. For the member and global variables, AspectC++ supports three types of join points: get, set, and ref join points. The get join point captures read access, as shown in the following example for the member variable length:

class Square {
  int length;
public:
  bool is_empty() {
    return length == 0;<== \pos{draw1}
  }
};

Likewise, the set join point refers to write access to a variable. The following code snippet shows a set join point for assignment to the global variable count:

length get join point

int count = 0;<== \pos{draw1}

int main() {
    count = 1;<== \pos{draw2}
}

-0.5cm

initialization of a variable

Note that the initialization of a global variable or member variable does not provide any set join point. The reason is that in C++, global variables are pre-initialized at once before the main() function is called. This pre-initialization is no event in the dynamic execution of the program and, thus, there is no dynamic join point either.

0.5cm

count set join point

Every get and set join point is associated with the fully qualified name of the respective variable, such as Square::length and count in the above examples. As such, the variable has be accessed by name to provide a get or set join point. In other words, there is no get or set join point on indirect access via pointer or reference without the variable name. But, member access via object pointer or object reference do provide get and set joint points, because the variable name is part of the access expression, as shown in the next example:

class Square {
  int length;
public:
  static Square* create() {
    Square* s = new Square;
    s->length = 0;<== \pos{draw1}
    return s;
  }
};

4cm

For advanced dealing with pointers and references, AspectC++ supports the ref join point. The ref join point captures two cases: First, obtaining the address of a member or global variable provides a ref join point. Second, the initialization or binding of a reference to such a variable provides another ref join point. The following code snippet illustrates both cases:

length set join point

int count = 0;

int main() {
    int* pointer = &count;<== \pos{draw1}
    int& reference = count;<== \pos{draw2}
}

count ref join points

The ref join point is particularly useful to restrict aliasing of variables, for example, to make sure that there are no references to a specific variable, so that get and set join points capture each read and write access to that variable, respectively.

0.55cm

Every ref join point is associated with the fully qualified name of the referenced variable. The get, set, and ref join points are furthermore associated with the name of function where the variable access takes place, much like the caller function for call join points. In the previous example, both ref join points are associated with the variable name count and the function name main. That function name can be used to filter out join points in other functions, for instance.

2.1.4 Built-in Operators

Since AspectC++ 2.0, there is experimental support for call join points on C++ built-in operators. The fully qualified name of the callee function is the operator name in this case, such as the comparison operator==, the division operator/, and so on. However, there are many limitations with this experimental feature (see AspectC++ Language Reference, Section 4.5). Use it with care!

2.2 Static Join Points

Beside the various dynamic join points described in the previous section, AspectC++ also supports the static join point for user-defined data types, such as classes and structs. The static join point is on the class and struct definition, respectively. It refers to the program structure and is therefore not executable. The following piece of code shows the static join point for the class Square:

class Square {<== \pos{draw1}
  /* ... */
};

Every static join point is associated with the fully qualified name of the respective data type, such as Square in the previous example. The static join point can be used to specify advice for introducing additional member variables, member functions, nested classes, and base classes into the respective data type.

-1cm

static join point

3 Aspects

The aspect is the central language element of AspectC++ to organize crosscutting concerns in a modular way. Aspects can be understood as an extension of the C++ class concept. That is, you can define an aspect much like you would define a class, except for using the keyword aspect instead of class. As such, aspect share many features of C++ classes:

Aspects can have member variables.
Aspects can have member functions, constructors, and destructors.
Aspects can inherit from classes.
Aspects are abstract if they declare or inherit a pure virtual member function.

Furthermore, aspects provide three additional features over classes:

Aspects can inherit from other aspects.

Aspects are typically instantiated automatically.

Aspects have pointcut definitions or advice or both (see Section 4 and 5).

Let’s ignore pointcut definitions and advice for now and let’s defer these concepts to later sections to focus on aspect design guidelines here: First, the AspectC++ developers consider the definition of an aspect in a separate header file as good design practice. Second, aspect header files always end with the .ah extension by convention. Third, aspect header files need include guards much like any other C++ header file. The example in Figure 1 illustrates the definition of an aspect conforming to these rules.

#ifndef __TRACING_AH__<== \pos{draw1}
#define __TRACING_AH__

#include <iostream>
#include <string>

aspect Tracing {<== \pos{draw2}
  unsigned int indentation_level = 0;<== \pos{draw3}

  void println(const char* line) {<== \pos{draw4}
    std::cout << std::string(indentation_level, ’ ’)
              << line << std::endl;
  }

  /* ... */<== \pos{draw5}
};<== \pos{draw6}

#endif /* __TRACING_AH__ */

draw1

2cm

-0.75cm

include guard

draw2

5cm

1.5cm

aspect definition using
the keyword aspect

draw3

1.0cm

0.5cm

member variable

draw4

1.5cm

0.5cm

member function

draw5

6cm

1cm

pointcut defintions and
advice (omitted here)

draw6

8cm

-1cm

closing bracket with
semicolon

Figure 1: Aspect definition in the separate header file Tracing.ah

3.1 Instantiation

The previous section mentioned that aspects are instantiated automatically. This means that you typically don’t create an object for an aspect manually. Aspects usually implement concerns that crosscut the whole program, and such aspects therefore need to exist for the whole program lifetime. Thus, the AspectC++ compiler automatically creates a single instance with static lifetime (i.e. one global object) for each aspect by default. Abstract aspects with pure virtual member functions are never instantiated. In almost all cases, you don’t have to care about instantiation at all.

However, you can still change the default instantiation scheme if needed, for example, to create one object for an aspect per thread (see Section 5 for an example).

3.2 Abstract Aspects

An aspect is abstract if it declares or inherits a pure virtual member function or a pure virtual pointcut (see next section). Just like abstract classes, abstract aspects cannot be instantiated. Other aspects can inherit from abstract aspects, and if a derived aspect defines all inherited pure virtual functions and pointcuts, the AspectC++ compiler instantiates the derived aspect eventually.

The reason for abstract aspects is code reuse of common functionality. Imagine you want to apply the aspect previously shown in Figure 1, but rather than printing to the standard output stream, you want it to print to the standard error output stream. The previously shown aspect can be rewritten as an abstract aspect with a pure virtual println function as shown in the following code snippet:

aspect Tracing {
protected:
  unsigned int indentation_level = 0;

  virtual void println(const char* line) = 0;<== \pos{draw1}

  /* ... */<== \pos{draw2}
};

draw1

0.8cm

2cm

pure
virtual
member
function

draw2

6cm

-1cm

pointcut defintions and
advice (omitted here)

The actual implementation of that println function can now be defined in a separate aspect for the respective output stream. For example, the following piece of code shows the derived aspect that prints to the standard error output stream:

aspect ErrorStreamTracing : public Tracing {<== \pos{draw1}

  void println(const char* line) override {<== \pos{draw2}
    std::cerr << std::string(indentation_level, ’ ’)
              << line << std::endl;
  }
};

draw1

0.5cm

inheritance

draw2

0.5cm

1cm

function im-
plementation

The derived aspect implements only one function and reuses all the functionality of the abstract base aspect. In this example, the abstract aspect allows the developer to define the printing functionality later and without code duplication. This design principle is particularly useful for aspects that allow for customization, such as aspects that are part of a program library.

4 Pointcuts

Pointcuts describe, or rather capture, a set of join points in the program. Given a pointcut, you can apply advice (see Section 5) on the captured join points to extend the program there. For example, you can insert additional program statements before the execution of the join points.

AspectC++ supports both anonymous and named pointcuts. You can define anonymous pointcuts at places where a pointcut expression is expected, for example, in line with the specification of advice (see Section 5). Named pointcuts, however, are defined much like functions. Typically, a named pointcut is defined as a member of an aspect, although it could be defined anywhere in the aspect header file where a function declaration is allowed. You can consider a named pointcut as a function that returns a set of join points, and you can reuse that pointcut in different parts of your aspect. A named pointcut is introduced by the keyword pointcut using the following syntax:

pointcut name(parameter-list) = pointcut-expression;

Let’s take a look at an example:

aspect CaptureDraw {
  pointcut draw() = "void Square::draw()";<== \pos{draw1}
};

draw1

0.5cm

1cm

named point-
cut and match
expression

The draw pointcut has an empty parameter list and is defined as a member of the shown aspect. The right hand side of the pointcut definition refers to the function Square::draw() that has, in turn, no parameters and that returns void. The pointcut expression on the right hand side is a match expression. It matches the fully qualified name Square::draw() and can be used to capture all join points involving that function. The next section describes the match expression syntax in detail.

A special pointcut expression is the value of 0, which is used to declare a named pointcut as pure virtual. Just like the declaration of a pure virtual function, such a pointcut must be declared using the keyword virtual as shown in the following code snippet:

virtual pointcut other() = 0;

Aspects with pure virtual pointcuts are abstract and thus not instantiated (see Section 3.2). It is up to derived aspects to define the pure virtual pointcuts and, thereby, to provide the pointcut expressions for capturing the relevant join points.

4.1 Match Expressions

Match expressions are used to define pointcut expressions as shown in the previous section. They describe a set of (statically) known program entities such as types/classes, variables, functions, or namespaces. A match expression can be understood as a search pattern. In such a search pattern the special character “%” is interpreted as a wildcard for names or parts of a signature. The special character sequence “…” matches any number of parameters in a function signature or any number of scopes in a qualified name. A match expression is a quoted string.

Examples for match expressions

"int C::%(...)": matches all member functions of the class C that return an int
"%List": matches any namespace, class, struct, union, or enum whose name ends with List.
"%: printf(const char *, ...)"
matches the function printf (defined in the global scope) having at least one parameter of type const char * and returning any type
"const %& ...::%(...)": matches all functions that return a reference to a constant object
"int* Puma::parsed_%": matches any pointer variable to the type int whose name starts with parsed_ and which is defined the scope Puma, which in turn can either be a namespace, a class, or a struct

Match expressions select program entities with respect to their definition scope, their type, and their name. The wildcard patterns turn match expressions into a powerful tool for selecting many join points at once, but you have to take care that you do not select too many – or too few – join points.

4.2 Attributes

Attributes allow you to define pointcut expressions without any match expression. You can select any program entity, such as a namespace, a class, a function, and a variable by applying one or several attributes to its definition. The following example shows the annotation of the function is_empty() with the C++ standard attribute [[nodiscard]], which primarily instructs the compiler to issue a warning when the return value is not used:

[[nodiscard]] bool is_empty() {<== \pos{draw}
  return length == 0;
}

draw

function annotation by
attribute nodiscard

-1cm

Given such a function annotation, you can now specify pointcut expressions that describe all such annotated functions. AspectC++ supports the declaration of attribute-based pointcut expressions using the attribute keyword and an empty parameter list as shown in the following code fragment:

attribute nodiscard();

After that declaration, the attribute can be used exactly like a named pointcut expression. In this specific example, the attribute declaration must take place in the global namespace, because the attribute [[nodiscard]] is already defined by the C++ standard there.

In addition to predefined standard attributes, AspectC++ supports user-defined attributes, which must be declared inside namespaces, classes, or aspects to avoid name conflicts with the standard attributes. A user-defined attribute has to be referenced later by its fully-qualified name. The following example shows the declaration and annotation of a function with a user-defined attribute:

class Square {
public:
  attribute onscreen();<== \pos{draw1}
  [[Square::onscreen]] void draw();<== \pos{draw2}
};

...

aspect ScreenByAttribute {
  pointcut screen() = Square::onscreen();<== \pos{draw3}
};

declaration of the user-defined
attribute onscreen in the class
Square

1.6cm

annotation of the
function draw with
the user-defined
attribute

0.7cm

-2.1cm

draw3

0.7cm