In order to correctly use AnvilJ it is necessary to understand the concept of AnvilJ Instances.

The input to the AnvilJ system is a normal Java application. In order to use AnvilJ's ability to distribute this application over the target architecture, the programmer designates some of the runtime instances of the application as "special" using an architecture definition file. These special instances are subjected to a set of restrictions (the rest of the application is not), the most significant of which is that it becomes a static instance that lasts for the entire duration of the application's runtime. These special instances are therefore "fixed points" in the application that the programmer can place throughout the target architecture using the architecture definition file. This lets the programmer say things like "Put this thread on this processor" or "Put this data structure on this processor" and AnvilJ will then work out what to do with the rest of the instances in the application so that its functional behaviour remains correct.

The name for these special instances are AnvilJ Threads and AnvilJ Shared Instances, or collectively, AnvilJ Instances. As their name implies, AnvilJ Threads are instances of java.lang.Thread or a descendent, and AnvilJ Shared Instances are instances of all other classes.

The question therefore becomes, "how much of my application do I need to mark as AnvilJ Instances?". The answer has two parts:

AnvilJ Instances are the unit of allocation

Part of the answer to that question is that AnvilJ Instances are the manner in which the programmer can place parts of the input application over the target architecture. Therefore, the number of AnvilJ Instances required will depend on how complex the desired allocation is, and how much fine-grained control the programmer desires. If the programmer needs to place a certain object instance on a certain node, it is necessary to mark it an as AnvilJ Instance.

All inter-node communications must end at an AnvilJ Instance

The second part of the answer is that enough of the application must be marked as an AnvilJ Instance so that the following rule is satisfied:

Normal Java threads can call methods and access fields of any instances on the local JVM. However, if a thread wishes to access an object instance which is located on a different node, the remote instance must be tagged as an AnvilJ Instance.

Clearly, the decision as to what is the "local JVM" can change depending on the allocation in the architecture definition. Therefore the programmer should ensure that their program is structured such that the allocatable units of their application communicate through well-defined interface classes. It is then sufficient to only have these interface classes marked as AnvilJ Instances.

Defining and allocating instances

AnvilJ Instances are defined and allocated to the nodes of the hardware using an architecture definition file, as described on this page.