cz.cuni.amis.pogamut.base.agent.module.comm

Class PogamutJVMComm

java.lang.Object

cz.cuni.amis.pogamut.base.agent.module.comm.PogamutJVMComm

public class PogamutJVMComm
extends Object

Simple support for inter-agent in-single-JVM communication. This object can be used for setting up simple communication via IWorldView. You can use getInstance() to obtain singleton-instance and register your agent to some channel using registerAgent(IObservingAgent, int). DO NOT FORGET TO USE unregisterAgent(IObservingAgent) once your agent has finished its lifecycle, otherwise you would likely to leak memory. Any agent may send events to registered agents at any time via send(IWorldChangeEvent, int) or broadcast(IWorldChangeEvent). The object uses IWorldChangeEventInput.notify(IWorldChangeEvent) to propagate events to respective agents' worldviews.

Author:

Jimmy

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	PogamutJVMComm.Broadcast
protected class	PogamutJVMComm.BroadcastToOthers
protected class	PogamutJVMComm.RegisterAgent
protected class	PogamutJVMComm.Send
protected class	PogamutJVMComm.SendToOthers
protected class	PogamutJVMComm.UnregisterAgent
protected class	PogamutJVMComm.UnregisterAgentFromChannel

Field Summary

Fields

Modifier and Type	Field and Description
static int	ALL_CHANNELS If you wish to listen on all CHANNELS you can use this constant.
protected Set<IObservingAgent>	allChannels Agents registered for "ALL_CHANNELS".
protected cz.cuni.amis.utils.maps.HashMapSet<Integer,IObservingAgent>	channels Agents registered for respective channels.
protected static ConcurrentLinkedQueue<PogamutJVMComm>	comms
protected ThreadPoolExecutor	executor
protected Object	executorMutex
protected static PogamutJVMComm	instance
protected static Object	instanceMutex
protected ReadWriteLock	lock Mutex for reading/writing channels/allChannels and sending events.
protected Logger	log
protected int	numberOfRegisterAgentPending
protected Object	numberOfRegisterAgentPendingMutex
protected Lock	readLock
protected Map<IAgentId,cz.cuni.amis.utils.Tuple2<IObservingAgent,Integer>>	registeredAgents AbstractAgent.getComponentId() maps to actual 'agent' registered + number of registration for a given agent.
protected Lock	writeLock

Constructor Summary

Constructors

Constructor and Description
PogamutJVMComm()
PogamutJVMComm(Logger log)

Method Summary

Methods

Modifier and Type	Method and Description
void	broadcast(IWorldChangeEvent event) Broadcast 'event' to all channels == all listening agents.
protected void	broadcastSyncImpl(IWorldChangeEvent event)
void	broadcastToOthers(IWorldChangeEvent event, IObservingAgent sender) Broadcast 'event' to all channels == all listening agents.
protected void	broadcastToOthersSyncImpl(IWorldChangeEvent event, IObservingAgent sender)
protected void	broadcastToOthersUnsyncImpl(IWorldChangeEvent event, IObservingAgent sender)
protected void	broadcastUnsyncImpl(IWorldChangeEvent event)
protected int	decRegisteredAgent(IObservingAgent agent)
void	destroy() UTILITY METHOD FOR DESTROYING THE COMMUNICATION.
protected void	execute(Runnable job, boolean forceStart)
protected Set<IObservingAgent>	getChannel(int channel)
static PogamutJVMComm	getInstance() Getter for JVM singleton.
Logger	getLog()
protected int	incRegisteredAgent(IObservingAgent agent)
boolean	isAgentRegistered(IObservingAgent agent, int channel) Whether an 'agent' is listening on 'channel'.
static void	platformClose()
void	registerAgent(IObservingAgent agent, int channel) Register an agent to receive events send through 'channel'.
protected void	registerAgentSyncImpl(IObservingAgent agent, int channel)
protected void	registerAgentUnsyncImpl(IObservingAgent agent, int channel)
void	send(IWorldChangeEvent event, int channel) Send 'event' to 'channel'.
protected void	sendSyncImpl(IWorldChangeEvent event, int channel)
protected void	sendToAgentUnsyncImpl(IObservingAgent agent, IWorldChangeEvent event)
void	sendToOthers(IWorldChangeEvent event, int channel, IObservingAgent sender) Send 'event' to 'channel' but does not notify 'sender'.
protected void	sendToOthersSyncImpl(IWorldChangeEvent event, int channel, IObservingAgent sender)
protected void	sendToOthersUnsyncImpl(IWorldChangeEvent event, int channel, IObservingAgent sender)
protected void	sendUnsyncImpl(IWorldChangeEvent event, int channel)
protected void	shutdown(boolean forced)
void	unregisterAgent(IObservingAgent agent) Totally unregister the agent (all channels + ALL_CHANNELS).
void	unregisterAgent(IObservingAgent agent, int channel) Removes agent from listening to some channels.
protected void	unregisterAgentSyncImpl(IObservingAgent agent)
protected void	unregisterAgentSyncImpl(IObservingAgent agent, int channel)
protected void	unregisterAgentUnsyncImpl(IObservingAgent agent)
protected void	unregisterAgentUnsyncImpl(IObservingAgent agent, int channel)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

instanceMutex

protected static Object instanceMutex

instance

protected static PogamutJVMComm instance

comms

protected static ConcurrentLinkedQueue<PogamutJVMComm> comms

ALL_CHANNELS

public static final int ALL_CHANNELS

If you wish to listen on all CHANNELS you can use this constant.

See Also:

Constant Field Values

registeredAgents

protected Map<IAgentId,cz.cuni.amis.utils.Tuple2<IObservingAgent,Integer>> registeredAgents

AbstractAgent.getComponentId() maps to actual 'agent' registered + number of registration for a given agent.

allChannels

protected Set<IObservingAgent> allChannels

Agents registered for "ALL_CHANNELS".

channels

protected cz.cuni.amis.utils.maps.HashMapSet<Integer,IObservingAgent> channels

Agents registered for respective channels.

lock

protected ReadWriteLock lock

Mutex for reading/writing channels/allChannels and sending events.

readLock

protected Lock readLock

writeLock

protected Lock writeLock

log

protected Logger log

executorMutex

protected Object executorMutex

executor

protected ThreadPoolExecutor executor

numberOfRegisterAgentPendingMutex

protected Object numberOfRegisterAgentPendingMutex

numberOfRegisterAgentPending

protected int numberOfRegisterAgentPending

Constructor Detail

PogamutJVMComm

public PogamutJVMComm()

PogamutJVMComm

public PogamutJVMComm(Logger log)

Parameters:

log - can be null, default will be provided

Method Detail

getInstance

public static PogamutJVMComm getInstance()

Getter for JVM singleton.

Returns:

platformClose

public static void platformClose()

getLog

public Logger getLog()

incRegisteredAgent

protected int incRegisteredAgent(IObservingAgent agent)

Parameters:

agent -

Returns:

how many times is 'agent' registered (after increase)

decRegisteredAgent

protected int decRegisteredAgent(IObservingAgent agent)

Parameters:

agent -

Returns:

how many times is 'agent' still registered (after decrease)

registerAgent

public void registerAgent(IObservingAgent agent,
                 int channel)

Register an agent to receive events send through 'channel'. Use ALL_CHANNELS constant to listen to all channels (existing or future).

Parameters:

agent -

channel -

registerAgentSyncImpl

protected void registerAgentSyncImpl(IObservingAgent agent,
                         int channel)

registerAgentUnsyncImpl

protected void registerAgentUnsyncImpl(IObservingAgent agent,
                           int channel)

isAgentRegistered

public boolean isAgentRegistered(IObservingAgent agent,
                        int channel)

Whether an 'agent' is listening on 'channel'. Use ALL_CHANNELS constant to check whether an agent is listening to ALL CHANNELS (existing and future). Potentially BLOCKING METHOD, waiting for readLock to be locked.

Parameters:

agent -

channel -

Returns:

getChannel

protected Set<IObservingAgent> getChannel(int channel)

unregisterAgent

public void unregisterAgent(IObservingAgent agent,
                   int channel)

Removes agent from listening to some channels. If you specify ALL_CHANNELS, agent is registered from ALL_CHANNELS (does not mean it is unregistered from respective channels, it is "unregister-from-broadcast-listening").

Parameters:

agent -

channel -

unregisterAgentSyncImpl

protected void unregisterAgentSyncImpl(IObservingAgent agent,
                           int channel)

unregisterAgentUnsyncImpl

protected void unregisterAgentUnsyncImpl(IObservingAgent agent,
                             int channel)

unregisterAgent

public void unregisterAgent(IObservingAgent agent)

Totally unregister the agent (all channels + ALL_CHANNELS).

Parameters:

bot -

unregisterAgentSyncImpl

protected void unregisterAgentSyncImpl(IObservingAgent agent)

unregisterAgentUnsyncImpl

protected void unregisterAgentUnsyncImpl(IObservingAgent agent)

send

public void send(IWorldChangeEvent event,
        int channel)

Send 'event' to 'channel'. Note that this version does not have "SENDER", thus it may notify even the SENDER with 'event' if it is subscribed to channel 'channel'. If you wish to "sendToAllOthers" use sendToOthers(IWorldChangeEvent, int, IObservingAgent).

Parameters:

event -

channel -

sendToOthers

public void sendToOthers(IWorldChangeEvent event,
                int channel,
                IObservingAgent sender)

Send 'event' to 'channel' but does not notify 'sender'. Note that 'sender' (that should be you) won't receive the 'event'.

Parameters:

event -

channel -

sendSyncImpl

protected void sendSyncImpl(IWorldChangeEvent event,
                int channel)

sendToOthersSyncImpl

protected void sendToOthersSyncImpl(IWorldChangeEvent event,
                        int channel,
                        IObservingAgent sender)

sendUnsyncImpl

protected void sendUnsyncImpl(IWorldChangeEvent event,
                  int channel)

sendToOthersUnsyncImpl

protected void sendToOthersUnsyncImpl(IWorldChangeEvent event,
                          int channel,
                          IObservingAgent sender)

sendToAgentUnsyncImpl

protected void sendToAgentUnsyncImpl(IObservingAgent agent,
                         IWorldChangeEvent event)

broadcast

public void broadcast(IWorldChangeEvent event)

Broadcast 'event' to all channels == all listening agents. Note that this version does not have "SENDER", thus it may notify even the SENDER with 'event' if it is subscribed to any / all channels. If you wish to "broadcastToAllOthers" use broadcastToOthers(IWorldChangeEvent, IObservingAgent).

Parameters:

event -

broadcastToOthers

public void broadcastToOthers(IWorldChangeEvent event,
                     IObservingAgent sender)

Broadcast 'event' to all channels == all listening agents. Note that 'sender' (that should be you) won't receive the 'event'.

Parameters:

event -

sender -

broadcastSyncImpl

protected void broadcastSyncImpl(IWorldChangeEvent event)

broadcastToOthersSyncImpl

protected void broadcastToOthersSyncImpl(IWorldChangeEvent event,
                             IObservingAgent sender)

broadcastUnsyncImpl

protected void broadcastUnsyncImpl(IWorldChangeEvent event)

broadcastToOthersUnsyncImpl

protected void broadcastToOthersUnsyncImpl(IWorldChangeEvent event,
                               IObservingAgent sender)

destroy

public void destroy()

UTILITY METHOD FOR DESTROYING THE COMMUNICATION. Call this method if you want the instance to be safely GC()ed. Note that PogamutPlatform.close() will call this for you on getInstance().

execute

protected void execute(Runnable job,
           boolean forceStart)

shutdown

protected void shutdown(boolean forced)