org.curjent.agent
Annotation Type Marker


@Documented
@Target(value=METHOD)
@Retention(value=RUNTIME)
public @interface Marker

Specifies that a call should not start executing until all prior calls have finished executing. Markers are useful for agents with two or more threads of execution (i.e., concurrently running tasks). Take, for example, the following three calls to an agent:

    void test(A a) {
        a.f1();
        a.f2();
        a.f3();
    }
 
An agent with one task, and therefore only one thread of execution, will execute these calls in the same order. However, if the agent can acquire two or more tasks, it can execute some or all of these calls concurrently. If the agent can acquire three tasks, these three calls could all run concurrently and finish executing in any order (although they would always start executing in the same order). This can make it difficult to run something, say method f3() in our example, after all prior calls have finished. Assume, for example, that f1() and f2() can run concurrently, but f3() is a cleanup method that cannot run until after f1() and f2() finish. Markers make this possible.

When a task's method is annotated with @Marker, the agent will not start executing a call for that method until all prior calls have finished executing.

This does not, however, preclude subsequent calls from executing. To illustrate this, let's extend our example to include two additional calls:

    void test(A a) {
        a.f1();
        a.f2();
        a.f3();
        a.f4();
        a.f5();
    }
 
In our extended example, let's say the task's methods for f3() and f5() are both annotated with @Marker. This ensures f3() will not start executing until f1() and f2() have finished executing, and f5() will not start executing until f4() has finished executing. It also ensures f5() will not start executing until f3() has finished executing.

However, it does not restrict the order of execution for the non-marker calls. The agent can execute f1(), f2(), and f4() simultaneously. The only restriction is that f3() cannot start executing until f1() and f2() have finished executing, and f5() cannot start executing until f3() and f4() have finished executing.

A method annotated with @Marker is a "trailing marker." A trailing marker starts executing after all prior calls have finished executing. The Leading annotation defines a "leading marker." A leading marker finishes executing before any subsequent calls start executing. The Isolated annotation defines an "isolated marker." An isolated marker starts executing after all prior calls have finished executing, and finishes executing before any subsequent calls start executing.

See Also:
Leading, Isolated



Copyright 2009-2011 Tom Landon
Apache License 2.0