MATES 3.0-rc2

org.mates.sim
Class Agent

java.lang.Object
  extended byorg.mates.sim.Agent
All Implemented Interfaces:
java.lang.Runnable

public abstract class Agent
extends java.lang.Object
implements java.lang.Runnable

Class from which all agents must be extended.

Author:
Evan Sultanik

Field Summary
protected  Host host
          The current host on which this agent resides.
 
Constructor Summary
Agent(Host host)
          Constructor for an agent with a priority of 0 and no name.
Agent(java.lang.String name, Host host)
          Constructor for an agent with a priority of 0.
Agent(java.lang.String name, Host host, int priority)
          Primary constructor for an agent.
 
Method Summary
 void die()
          Kills this agent.
 boolean getDieOnMigrationFailure()
          Returns whether or not an agent will die if its migration fails.
 java.awt.Component getGUI()
          Returns a graphical component for the interface of this agent.
 Host getHost()
          Returns the current host this agent is on.
 int getMigrationTimeout()
          Accessor for the migration timeout of this agent
 java.lang.String getName()
          Returns the name of this agent.
 int getPriority()
          Accessor for the priority of this agent.
protected  Simulator getSimulator()
          Internal accessor for the simulator that this agent is currently running within.
 double getTransmissionSize()
          Accessor for the virtual size of this agent.
 UniqueID getUniqueID()
          Returns the unique identifier for this agent.
 boolean isAlive()
          Returns true if this agent is currently alive.
 boolean isAsleep()
          Returns true if this agent is currently asleep.
 boolean isConsumingProcessor()
          Returns whether or not this agent will consume its hosts processor while it is sleeping.
 void iterate()
          This function is called once every time the agent is scheduled (by its host) to run.
 void log(java.lang.String message)
          Prints a log message attributed to this agent.
protected  boolean migrate(Host new_host)
          Instructs this agent to migrate to a new host.
abstract  void run()
          This function contains the execution code of the agent.
 void setDieOnMigrationFailure(boolean die)
          Sets whether or not an agent will die if its migration fails.
 void setHost(Host new_host)
          Sets the host of this agent.
 void setMigrationTimeout(int migration_timeout)
          Sets the migration timeout for this agent.
 void setPriority(int priority)
          Sets the priority of this agent.
 void setTransmissionSize(double size)
          Sets the virtual size of this agent.
 void sleep(long iterations)
          Instructs this agent to sleep for a specified number of iterations.
 void sleep(long iterations, boolean consume_processor)
          Instructs this agent to sleep for a specified number of iterations.
 java.lang.String toString()
           
 void yield()
          Yeilds execution of this agent to all other agents, for one iteration.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

host

protected Host host
The current host on which this agent resides. Generally, this variable should only be internally modified by the simulator itself.

Constructor Detail

Agent

public Agent(java.lang.String name,
             Host host,
             int priority)
Primary constructor for an agent.

Parameters:
name - a not-necessarily-unique name for this agent. This is mostly for debugging and conveniance. This may be null.
host - the host on which this agent is to be spawned.
priority - any integer value for the priority of this agent.
See Also:
setPriority(int)

Agent

public Agent(java.lang.String name,
             Host host)
Constructor for an agent with a priority of 0.

See Also:
Agent(String, Host, int)

Agent

public Agent(Host host)
Constructor for an agent with a priority of 0 and no name.

See Also:
Agent(String, Host, int)
Method Detail

log

public void log(java.lang.String message)
Prints a log message attributed to this agent. This function essentially calls getSimulator().log(this, message).

Parameters:
message - the message to be logged.
See Also:
Simulator.log(Object, String)

setDieOnMigrationFailure

public void setDieOnMigrationFailure(boolean die)
Sets whether or not an agent will die if its migration fails. If false, the default, an agent will return to its sender if its migration fails.


getDieOnMigrationFailure

public boolean getDieOnMigrationFailure()
Returns whether or not an agent will die if its migration fails. If false, the default, an agent will return to its sender if its migration fails.


setTransmissionSize

public void setTransmissionSize(double size)
Sets the virtual size of this agent.

Parameters:
size - roughly equates to the number of iterations required to transmit this agent with maximum connectivity.

getTransmissionSize

public double getTransmissionSize()
Accessor for the virtual size of this agent.

Returns:
the virtual size of this agent.
See Also:
setTransmissionSize(double)

getMigrationTimeout

public int getMigrationTimeout()
Accessor for the migration timeout of this agent

Returns:
the migration timeout for this agent.
See Also:
setMigrationTimeout(int migration_timeout)

setMigrationTimeout

public void setMigrationTimeout(int migration_timeout)
Sets the migration timeout for this agent.

Parameters:
migration_timeout - the number of iterations this agent will wait before giving up on migrating to another host.
See Also:
migrate(Host)

getSimulator

protected Simulator getSimulator()
Internal accessor for the simulator that this agent is currently running within. This essentially calles host.getSimulator().


run

public abstract void run()
This function contains the execution code of the agent. run() is called once, the first time an agent is scheduled to execute by its host. The simulator will block while this function is executing. It is intended that the implementation of this function will use blocking functions like sleep(long) and migrate(Host) to return control to the simulation. Whenever execution reaches the end of this function (i.e. whenever run() returns), this agent will die.

Specified by:
run in interface java.lang.Runnable

iterate

public final void iterate()
This function is called once every time the agent is scheduled (by its host) to run.


yield

public void yield()
Yeilds execution of this agent to all other agents, for one iteration. Equivalent to sleep(1, false).


sleep

public void sleep(long iterations)
Instructs this agent to sleep for a specified number of iterations. This call is equivalent to sleep(iterations, false).

Parameters:
iterations - The number of iterations to sleep.

sleep

public void sleep(long iterations,
                  boolean consume_processor)
Instructs this agent to sleep for a specified number of iterations. If this agent is currently asleep, it will sleep for an additional iterations.

If called from within this agent's run() function, this function will block until the specified number of iterations have elapsed.

Parameters:
iterations - The number of iterations to sleep.
consume_processor - if true, while this agent is sleeping it will still consume the processing power of its host (thus reducing the amount of processing time that goes to other agents on that host). This provides a means of simulating agent processes that would be processor intensive.

getPriority

public int getPriority()
Accessor for the priority of this agent.

Returns:
the priority of this agent
See Also:
setPriority(int)

isAlive

public boolean isAlive()
Returns true if this agent is currently alive.

Returns:
true if this agent is currently alive.
See Also:
die()

isAsleep

public boolean isAsleep()
Returns true if this agent is currently asleep.


die

public void die()
Kills this agent. The agent will no longer be a part of the simulator. This function essentially calls getSimulator().killAgent(this)


migrate

protected boolean migrate(Host new_host)
Instructs this agent to migrate to a new host. If this function is called from within the run() function of this agent, it will block until the agent has arrived at the new host. Otherwise, if this function is called from anywhere else, this agent will simply be instructed to migrate and the function will ensure that the agent's current host and new_host are in communication range. host is null while the agent is in transit. If caled from outside the run() function, this function will immediately schedule the migration, even if the agent is currently sleeping.

Parameters:
new_host - the host to migrate to
Returns:
If called from within the run() function of this agent, true will be returned when and if the migration is completed and successful. If called from any other location, this function returns true if the migration is valid. In other words, new_host is a valid destination and this agent is not already in the process of migrating. This return value ensures that the migration process has started; it has nothing to do with the success or completion of the migration.
See Also:
Simulator.migrate(Agent, Host)

setHost

public void setHost(Host new_host)
Sets the host of this agent. This assignment takes effect immediately. Normally, one will want to use migrate(Host).

Parameters:
new_host - the new host for this agent.
See Also:
migrate(Host)

getHost

public Host getHost()
Returns the current host this agent is on.

Returns:
the current host this agent is on.

setPriority

public void setPriority(int priority)
Sets the priority of this agent. The higher the priority, the more virtual CPU time this agent will get, compared to agents of lesser priority on its current host.

Parameters:
priority - an integer value for the priority of this agent.

getName

public java.lang.String getName()
Returns the name of this agent. Note that this function may return null.

Returns:
the name of this agent (may be null).

getUniqueID

public UniqueID getUniqueID()
Returns the unique identifier for this agent.

Returns:
the unique identifier for this agent.

getGUI

public java.awt.Component getGUI()
Returns a graphical component for the interface of this agent. This component will then be displayed if GraphicalUserInterface is used. This function defaults to return null. getGUI() is intended for child classes that extend Agent to re-implement this function and return a GUI object.

Returns:
a graphical component for the interface of this agent.

isConsumingProcessor

public boolean isConsumingProcessor()
Returns whether or not this agent will consume its hosts processor while it is sleeping.


toString

public java.lang.String toString()

MATES 3.0-rc2

Submit a bug or request a feature
http://mates.sourceforge.net/

Copyright 2004 Evan Sultanik