org.actorsguildframework.annotations
Annotation Type Shared

@Target(value={PARAMETER,FIELD,METHOD})
@Retention(value=RUNTIME)
public @interface Shared

The Shared annotation is used to state that a variable, field or property refers to a thread-safe object that can be shared among actors.

@Shared is used for three purposes:

1. In a method argument with Message annotations, to mark an argument as shared between caller and called actor
2. In a field of an Actor, to mark the field as refering to an object that can be safely used in a ConcurrencyModel.Stateless actor or method
3. In a Prop annotated getter, to mark the property as refering to an object that can be safely used in a ConcurrencyModel.Stateless actor or method

In any case, the class marjed as as @Shared must be fully multi-thead-safe, as they will be used in several threads simultanously.

@Shared in Method Arguments

The effect of @Shared in method arguments is that the argument will always be parsed by reference, and thus it is shared by both caller and callee. This is useful if you have an object that can not be Serialized and is not an Actor.

@Shared as method argument annotation should be avoided if possible, as shared can only work if caller and callee run in the same VM. Currently ActorsGuild supports only actors in the same VM, and thus it will always work, but in future versions this may be different.

Example:

@Message
 public AsyncResult sendMessage(@Shared Socket socket, String msg) throws Exception {
        try {
                String path = HTTPHelper.readHeader(socket.getInputStream());
      BufferedWriter bw = new BufferedWriter(new OutputStreamWriter(socket.getOutputStream()));
      bw.write(msg);
      bw.flush();
        }
        finally {
                socket.close();
        }
        return noResult();
 }
 

@Shared in Fields and @Prop properties

As ConcurrencyModel.Stateless actors must not have any state, it is forbidden for them to have any non-final field, but they actors to be configured at their creation with final fields referring to Immutable values or actors. However, an exception is being made for final fields annotated with @Shared. This is needed sometimes, for example to configure a JDBC DataSource.

ConcurrencyModel.Stateless messages in non-stateless actors are required to use only stateless fields of the actor, thus final fields refering to immutable values, actors or that use a @Shared annotation.