org.curjent.agent
Interface CallSite

public interface CallSite

Metadata and configuration for an agent's method.

Each call site is a unique instance for each agent instance. For example:

  interface Printer {
      void print(Document document);
  }
  
  class PrinterTask implements Printer {
      public void print(Document document) { ... }
  }
  
  Printer a = Agent.newInstance(Printer.class, new PrinterTask());
  Printer b = Agent.newInstance(Printer.class, new PrinterTask());
  
  assert a != b;
  
  CallSite x = Agent.getConfig(a).getCallSite("print", void.class, Document.class);
  CallSite y = Agent.getConfig(b).getCallSite("print", void.class, Document.class);
  
  assert x.getAgent() == a;
  assert y.getAgent() == b;
  
  assert x == Agent.getConfig(a).getCallSite("print", void.class, Document.class);
  assert y == Agent.getConfig(b).getCallSite("print", void.class, Document.class);
  assert x != y;
 

Agents a and b are unique agent instances. Therefore, call sites x and y are unique call site instances.

Each unique interface method has a corresponding call site. There is a one-to-one relationship between unique interface methods and call sites. On the other hand, multiple call sites may map to the same task method. For example:

  interface A { Object f(); }
  interface B { void f(int x); }
  interface C { Object f(); }
  interface D { String f(); }
  
  class R implements A, B, C, D {
      public String f() { return "abc"; }
      public void f(int x) {}
  }
  
  R r = Agent.newInstance(
      new DelegatingLoader(this),
      new Class[]{A.class, B.class, C.class, D.class},
      new SingletonTask(new R()),
      R.class);
  
  AgentConfig config = Agent.getConfig(r);
  
  CallSite a = config.getCallSite("f", Object.class);
  CallSite b = config.getCallSite("f", void.class, int.class);
  CallSite c = config.getCallSite("f", Object.class);
  CallSite d = config.getCallSite("f", String.class);
  
  assert (a != b) && (a == c) && (a != d) && (b != d);
  
  Method x = a.getInterfaceMethod(); // Object f()
  Method y = b.getInterfaceMethod(); // void f(int)
  Method z = d.getInterfaceMethod(); // String f()
  
  assert (x != y) && (x != z) && (y != z);
  assert x.getDeclaringClass() == A.class; // not C.class
  assert y.getDeclaringClass() == B.class;
  assert z.getDeclaringClass() == D.class;
  
  Method u = a.getTaskMethod(); // Object f()
  Method v = b.getTaskMethod(); // void f(int)
  Method w = d.getTaskMethod(); // Object f()
  
  assert (u == w) && (u != v);
 

Interface C's method (Object f()) is an exact duplicate of interface A's method (Object f()). There is no call site for interface C's method since the call to Agent.newInstance() listed interface A first.

Java defines interface A's method as distinct from interface D's method since they have different return types. But both interface methods map to the same method in class R (Object f()). This is valid so long as both return types are compatible (i.e., String is a subclass of Object) and the task returns a value that is compatible with both return types.

See Also:

AgentConfig.getCallSite(String, Class, Class...)

Method Summary

Object	getAgent() Returns this call site's agent.
CallStateListener<?>	getCallStateListener() Returns the default call state listener for this agent's call site.
CallStateListener<?>	getCallStateListener(CallState state) Returns the default listener for the given call state.
Object	getData() Returns the data previously associated with this call site.
long	getExpirationTimeout() Returns the default call expiration timeout for calls of this site that are not individually configured with expiration timeouts.
TimeUnit	getExpirationTimeoutUnit() Returns the default call expiration timeout unit for this site.
Method	getInterfaceMethod() Returns the interface's method for this call site.
MarkerType	getMarkerType() Returns the type of Marker.
Method	getTaskMethod() Returns the task's method for this call site.
boolean	isFuture() Returns true if this call site is asynchronous and the interface method's return type is Future or AgentCall.
boolean	isReentrant() Returns true if the task's method is annotated with Reentrant.
boolean	isSynchronous() Returns true if this call site is implicitly or explicitly synchronous.
boolean	isSynthetic() Returns true if this is a non-standard agent call.
void	setCallStateListener(CallState state, CallStateListener<?> listener) Sets a listener for the given call state.
void	setCallStateListener(CallStateListener<?> listener) Sets a default call state listener for this agent's call site.
void	setData(Object data) Associates data with this agent's call site.
void	setExpirationTimeout(long value, TimeUnit unit) Sets the default call expiration for calls of this site that are not individually configured with expiration timeouts.

Method Detail

getAgent

Object getAgent()

Returns this call site's agent.

getInterfaceMethod

Method getInterfaceMethod()

Returns the interface's method for this call site.

getTaskMethod

Method getTaskMethod()

Returns the task's method for this call site.

isFuture

boolean isFuture()

Returns true if this call site is asynchronous and the interface method's return type is Future or AgentCall.

isSynchronous

boolean isSynchronous()

Returns true if this call site is implicitly or explicitly synchronous. A call site is implicitly synchronous if its interface method's return type is non-null and neither Future nor AgentCall. It is explicitly synchronous regardless of its return type if its task method is annotated as Synchronous.

isReentrant

boolean isReentrant()

Returns true if the task's method is annotated with Reentrant.

isSynthetic

boolean isSynthetic()

Returns true if this is a non-standard agent call. Agent.mark(Object), for example, creates a synthetic call via AgentMark.call(). Synthetic calls behave like standard calls in most ways but are largely invisible to most users of an agent. For example, synthetic calls are excluded from the current pending, accepted, and executing counts in AgentStats. They are also excluded from pending and accepted capacity limits (see Capacity). And unlike standard calls, callers are not suspended when the maximum number of accepted calls has been reached (e.g., AgentMark.call() always returns immediately and never suspends the caller). The standard call state listeners configured via AgentConfig are not called for synthetic calls, either.

getMarkerType

MarkerType getMarkerType()

Returns the type of Marker. Returns null for non-marker calls.

getExpirationTimeout

long getExpirationTimeout()

Returns the default call expiration timeout for calls of this site that are not individually configured with expiration timeouts.

See Also:

getExpirationTimeoutUnit(), Expiration

getExpirationTimeoutUnit

TimeUnit getExpirationTimeoutUnit()

Returns the default call expiration timeout unit for this site.

See Also:

getExpirationTimeout(), Expiration

setExpirationTimeout

void setExpirationTimeout(long value,
                          TimeUnit unit)

Sets the default call expiration for calls of this site that are not individually configured with expiration timeouts.

Throws:

IllegalArgumentException - value is less than 1.

NullPointerException - unit is null and value is not Long.MAX_VALUE

See Also:

Expiration

getCallStateListener

CallStateListener<?> getCallStateListener()

Returns the default call state listener for this agent's call site. Returns null if none has been assigned.

See Also:

setCallStateListener(CallStateListener)

setCallStateListener

void setCallStateListener(CallStateListener<?> listener)

Sets a default call state listener for this agent's call site. Clears the default listener if the given listener is null. See CallStateListener for details on the relationship between a call site's default listener and other listeners.

See Also:

setCallStateListener(CallState, CallStateListener), AgentConfig.setCallStateListener(CallStateListener), AgentConfig.setCallStateListener(CallState, CallStateListener)

getCallStateListener

CallStateListener<?> getCallStateListener(CallState state)

Returns the default listener for the given call state. Returns null if none has been assigned.

Throws:

NullPointerException - state is null

See Also:

setCallStateListener(CallState, CallStateListener)

setCallStateListener

void setCallStateListener(CallState state,
                          CallStateListener<?> listener)

Sets a listener for the given call state. Clears the listener for the given state if the given listener is null. See CallStateListener for details on the relationship between a call site's listener for a specific state and other listeners.

Throws:

NullPointerException - state is null

See Also:

setCallStateListener(CallStateListener), AgentConfig.setCallStateListener(CallStateListener), AgentConfig.setCallStateListener(CallState, CallStateListener)

getData

Object getData()

Returns the data previously associated with this call site. Returns null if none.

See Also:

setData(Object)

setData

void setData(Object data)

Associates data with this agent's call site. Any value is valid, including null.

See Also:

AgentConfig.setData(Object), AgentCall.setData(Object)