CloudSim源代码之SimEntity

package org.cloudbus.cloudsim.core;

import org.cloudbus.cloudsim.Log;
import org.cloudbus.cloudsim.NetworkTopology;
import org.cloudbus.cloudsim.core.predicates.Predicate;

/* 仿真实体 */

/* This class represents a simulation entity. An entity handles events
and can send events to other entities.When this class is extended,
there are a few methods that need to be implemented:

【startEntity()】is invoked by the class when the simulation is started.
this method should be responsible for starting the entity up. 

【processEvent(SimEvent)】is invoked by the Simulation class whenever 
there is an event in the deferred queue, which needs to be  invoked by 
the entity.

【shutdownEntity()】is invoked before the simulation finishes. If you 
want to save data in log files this is the method in which the corresponding 
code would be placed. */

public abstract class SimEntity implements Cloneable{
    private String name;       //名称
    private int id;            //编号
    private SimEvent evbuf;    //选定将来临的事件缓冲
    private int state;         //实体现在状态
    
    //创建新实体
    public SimEntity(String name) {
        if (name.indexOf(" ") != -1) {
            throw new IllegalArgumentException(
                    "Entity names can‘t contain spaces.");
        }
        this.name = name;
        id = -1;
        state = RUNNABLE; //运行
        CloudSim.addEntity(this);
    }
    
    //实体名
    public String getName() {
        return name;
    }
    
    //分配给实体的ID号
    public int getId() {
        return id;
    }
    
    /* 通过ID发送一事件到另一实体   含数据
     * @param dest 【目的实体ID】The unique id number of the destination entity
     * @param delay 【延迟时间】How long from the current simulation time the event should be sent
     * @param tag 【事件类型】An user-defined number representing the type of event.
     * @param data 【事件传递的数据】 The data to be sent with the event.*/
     
    public void schedule(int dest, double delay, int tag, Object data) {
        if (!CloudSim.running()) {
            return;
        }
        CloudSim.send(id, dest, delay, tag, data);
    }
    
    /* 通过ID发送一事件到另一实体   无数据 
     * @param dest The unique id number of the destination entity
     * @param delay How long from the current simulation time the event should be sent
     * @param tag An user-defined number representing the type of event.*/
     
    public void schedule(int dest, double delay, int tag) {
        schedule(dest, delay, tag, null);               //data为null
    }
    
    /* 通过给定的端口发送一事件到另一实体   含数据
     * @param dest 【端口】The name of the port to send the event through
     * @param delay How long from the current simulation time the event
     * should be sent
     * @param tag An user-defined number representing the type of event.
     * @param data The data to be sent with the event.*/
     
    public void schedule(String dest, double delay, int tag, Object data) {
        schedule(CloudSim.getEntityId(dest), delay, tag, data);      //注意与上面对比
    }

    /* 通过给定的端口发送一事件到另一实体   无数据
     * @param dest The name of the port to send the event through
     * @param delay How long from the current simulation time the event should be
     * sent
     * @param tag An user-defined number representing the type of event.*/
     
    public void schedule(String dest, double delay, int tag) {
        schedule(dest, delay, tag, null);
    }
    
    /* 通过ID发送一事件给另一实体  含数据
     * @param dest The unique id number of the destination entity
     * @param tag An user-defined number representing the type of event.
     * @param data The data to be sent with the event.*/
     
    public void scheduleNow(int dest, int tag, Object data) {
        schedule(dest, 0, tag, data);       //现在的delay为0
    }
    
    /*通过ID发送一事件给另一实体  无数据
     * @param dest The unique id number of the destination entity
     * @param tag An user-defined number representing the type of event.*/
     
    public void scheduleNow(int dest, int tag) {
        schedule(dest, 0, tag, null);
    }

    /* 通过给定的端口发送一事件到另一实体   含数据
     * @param dest The name of the port to send the event through
     * @param tag An user-defined number representing the type of event.
     * @param data The data to be sent with the event.*/
    
    public void scheduleNow(String dest, int tag, Object data) {
        schedule(CloudSim.getEntityId(dest), 0, tag, data);
    }
    
    /* 通过给定的端口发送一事件到另一实体   不含数据
     * @param dest The name of the port to send the event through
     * @param tag An user-defined number representing the type of event.*/
    
    public void scheduleNow(String dest, int tag) {
        schedule(dest, 0, tag, null);
    }

    /* 设置实体一段时间闲置
     * @param delay the time period for which the entity will be inactive
     */
    public void pause(double delay) {
        if (delay < 0) {
            throw new IllegalArgumentException("Negative delay supplied.");
        }
        if (!CloudSim.running()) {
            return;
        }
        CloudSim.pause(id, delay);
    }
    
    /* 统计实体延期队列中多少个事件匹配等待
     * @param p The event selection predicate
     * @return The count of matching events
     */
    
    public int numEventsWaiting(Predicate p) {
        return CloudSim.waiting(id, p);
    }

    /* 统计实体延期队列中多少个事件等待
     * @return The count of events
     */
     
    public int numEventsWaiting() {
        return CloudSim.waiting(id, CloudSim.SIM_ANY);
    }

    /* 抽出第一个满足谓词p的事件
     * @param p The event selection predicate
     * @return the simulation event
     */
    public SimEvent selectEvent(Predicate p) {
        if (!CloudSim.running()) {
            return null;
        }
        return CloudSim.select(id, p);
    }
    
    /**取消第一个匹配等待事件
     * Cancel the first event matching a predicate waiting in the entity‘s
     * future queue.
     *
     * @param p The event selection predicate
     *
     * @return The number of events cancelled (0 or 1)
     */
    public SimEvent cancelEvent(Predicate p) {
        if (!CloudSim.running()) {
            return null;
        }

        return CloudSim.cancel(id, p);
    }

    /**延期队列第一个匹配事件
     * Get the first event matching a predicate from the deferred queue, or if
     * none match, wait for a matching event to arrive.
     *
     * @param p The predicate to match
     *
     * @return the simulation event
     */
    public SimEvent getNextEvent(Predicate p) {
        if (!CloudSim.running()) {
            return null;
        }
        if (numEventsWaiting(p) > 0) {
            return selectEvent(p);
        }
        return null;
    }

    /**等待匹配事件
     * Wait for an event matching a specific predicate. This method does not
     * check the entity‘s deferred queue.
     *
     * @param p The predicate to match
     */
    public void waitForEvent(Predicate p) {
        if (!CloudSim.running()) {
            return;
        }

        CloudSim.wait(id, p);
        this.state = WAITING;
    }

    /**等候在实体延期队列中的第一个事件
     * Get the first event waiting in the entity‘s deferred queue, or if there
     * are none, wait for an event to arrive.
     *
     * @return the simulation event
     */
    public SimEvent getNextEvent() {
        return getNextEvent(CloudSim.SIM_ANY);
    }

    /**【仿真开始】
     * This method is invoked by the class when
     * the simulation is started. This method should be responsible for starting the
     * entity up.
     */
    public abstract void startEntity();

    /**【处理事件】
     * This method is invoked by the {@link Simulation}
     * class whenever there is an event in the deferred queue, which needs to be
     * processed by the entity.
     *
     * @param ev the event to be processed by the entity
     */
    public abstract void processEvent(SimEvent ev);

    /**【仿真结束】
     * This method is invoked by the {@link Simulation} before the
     * simulation finishes. If you want to save data in log files this is the method
     * in which the corresponding code would be placed.
     */
    public abstract void shutdownEntity();

    public void run() {
        SimEvent ev = (evbuf != null ? evbuf : getNextEvent());

        while (ev != null) {
            processEvent(ev);
            if (state != RUNNABLE) {
                break;
            }

            ev = getNextEvent();
        }

        evbuf = null;
    }

    /**【克隆实体】
     * Get a clone of the entity. This is used when independent replications
     * have been specified as an output analysis method. Clones or backups of
     * the entities are made in the beginning of the simulation in order to
     * reset the entities for each subsequent replication. This method should
     * not be called by the user.
     *
     * @return A clone of the entity
     *
     * @throws CloneNotSupportedException the clone not supported exception
     */
    @Override
    protected final Object clone() throws CloneNotSupportedException {
        SimEntity copy = (SimEntity) super.clone();
        copy.setName(name);
        copy.setEventBuffer(null);
        return copy;
    }

    // Used to set a cloned entity‘s name
    /**实体名
     * Sets the name.
     *
     * @param new_name the new name
     */
    private void setName(String new_name) {
        name = new_name;
    }

    // --------------- PACKAGE LEVEL METHODS ------------------

    /**状态
     * Gets the state.
     *
     * @return the state
     */
    protected int getState() {
        return state;
    }

    /**事件缓冲
     * Gets the event buffer.
     *
     * @return the event buffer
     */
    protected SimEvent getEventBuffer() {
        return evbuf;
    }

    // The entity states
    /** The Constant RUNNABLE. 运行 */
    public static final int RUNNABLE = 0;

    /** The Constant WAITING. 等候*/
    public static final int WAITING = 1;

    /** The Constant HOLDING. 保持*/
    public static final int HOLDING = 2;

    /** The Constant FINISHED. 完成*/
    public static final int FINISHED = 3;

    /**设置状态
     * Sets the state.
     *
     * @param state the new state
     */
    protected void setState(int state) {
        this.state = state;
    }

    /**设置ID
     * Sets the id.
     *
     * @param id the new id
     */
    protected void setId(int id) {
        this.id = id;
    }

    /**设置事件缓冲
     * Sets the event buffer.
     *
     * @param e the new event buffer
     */
    protected void setEventBuffer(SimEvent e) {
        evbuf = e;
    }

    // --------------- EVENT / MESSAGE SEND WITH NETWORK DELAY METHODS ------------------

    /**发送事件到另一个实体
     * Sends an event/message to another entity by <tt>delaying</tt>
     * the simulation time from the current time, with a tag representing
     * the event type.
     *
     * @param entityId   the id number of the destination entity
     * @param delay      how long from the current simulation time the event
     * should be sent.
     * If delay is a negative number, then it will be
     * changed to 0
     * @param cloudSimTag an user-defined number representing the type of
     * an event/message
     * @param data       A reference to data to be sent with the event
     *
     * @pre entityID > 0
     * @pre delay >= 0.0
     * @pre data != null
     * @post $none
     */
    protected void send(int entityId, double delay, int cloudSimTag, Object data) {
        if (entityId < 0) {
            return;
        }
        if (delay < 0) {
            delay = 0;
        }
        if (Double.isInfinite(delay)) {
            throw new IllegalArgumentException("The specified delay is infinite value");
        }
        if (entityId < 0) {
            Log.printLine(getName() + ".send(): Error - " +
                    "invalid entity id " + entityId);
            return;
        }
        int srcId = getId();
        if (entityId != srcId) {// does not delay self messages
            delay += getNetworkDelay(srcId, entityId);
        }
        schedule(entityId, delay, cloudSimTag, data);
    }


    /**发送事件到另一个实体  无延迟
     * Sends an event/message to another entity by delaying the
     * simulation time from the current time, with a tag representing
     * the event type.
     *
     * @param entityId   the id number of the destination entity
     * @param delay      how long from the current simulation time the event
     * should be sent.
     * If delay is a negative number, then it will be
     * changed to 0
     * @param cloudSimTag an user-defined number representing the type of
     * an event/message
     *
     * @pre entityID > 0
     * @pre delay >= 0.0
     * @post $none
     */
    protected void send(int entityId, double delay, int cloudSimTag) {
        send(entityId, delay, cloudSimTag, null);
    }

    /**发送事件到另一个实体 延迟 标签代表事件类型
     * Sends an event/message to another entity by delaying
     * the simulation time from the current time, with a tag representing the
     * event type.
     *
     * @param entityName the name of the destination entity
     * @param delay      how long from the current simulation time the event
     * should be sent.
     * If delay is a negative number, then it will be
     * changed to 0
     * @param cloudSimTag an user-defined number representing the type of
     * an event/message
     * @param data       A reference to data to be sent with the event
     *
     * @pre entityName != null
     * @pre delay >= 0.0
     * @pre data != null
     * @post $none
     */
    protected void send(String entityName, double delay, int cloudSimTag, Object data) {
        send(CloudSim.getEntityId(entityName), delay, cloudSimTag, data);//注意与上面比较
    }

    /**
     * Sends an event/message to another entity by delaying
     * the simulation time from the current time, with a tag representing
     * the event type.
     *
     * @param entityName the name of the destination entity
     * @param delay      how long from the current simulation time the event
     * should be sent.
     * If delay is a negative number, then it will be
     * changed to 0
     * @param cloudSimTag an user-defined number representing the type of
     * an event/message
     *
     * @pre entityName != null
     * @pre delay >= 0.0
     * @post $none
     */
    protected void send(String entityName, double delay, int cloudSimTag) {
        send(entityName, delay, cloudSimTag, null);
    }

    /**注意与上面几个比较
     * Sends an event/message to another entity by <tt>delaying</tt>
     * the simulation time from the current time, with a tag representing
     * the event type.
     *
     * @param entityId   the id number of the destination entity
     * @param delay      how long from the current simulation time the event
     * should be sent.
     * If delay is a negative number, then it will be
     * changed to 0
     * @param cloudSimTag an user-defined number representing the type of
     * an event/message
     * @param data       A reference to data to be sent with the event
     *
     * @pre entityID > 0
     * @pre delay >= 0.0
     * @pre data != null
     * @post $none
     */
    protected void sendNow(int entityId, int cloudSimTag, Object data) {
        send(entityId, 0, cloudSimTag, data);
    }

    /**
     * Sends an event/message to another entity by <tt>delaying</tt> the
     * simulation time from the current time, with a tag representing
     * the event type.
     *
     * @param entityId   the id number of the destination entity
     * @param delay      how long from the current simulation time the event
     * should be sent.
     * If delay is a negative number, then it will be
     * changed to 0
     * @param cloudSimTag an user-defined number representing the type of
     * an event/message
     *
     * @pre entityID > 0
     * @pre delay >= 0.0
     * @post $none
     */
    protected void sendNow(int entityId, int cloudSimTag) {
        send(entityId, 0, cloudSimTag, null);
    }

    /**
     * Sends an event/message to another entity by <tt>delaying</tt>
     * the simulation time from the current time, with a tag representing the
     * event type.
     *
     * @param entityName the name of the destination entity
     * @param delay      how long from the current simulation time the event
     * should be sent.
     * If delay is a negative number, then it will be
     * changed to 0
     * @param cloudSimTag an user-defined number representing the type of
     * an event/message
     * @param data       A reference to data to be sent with the event
     *
     * @pre entityName != null
     * @pre delay >= 0.0
     * @pre data != null
     * @post $none
     */
    protected void sendNow(String entityName, int cloudSimTag, Object data) {
        send(CloudSim.getEntityId(entityName), 0, cloudSimTag, data);
    }

    /**
     * Sends an event/message to another entity by <tt>delaying</tt>
     * the simulation time from the current time, with a tag representing
     * the event type.
     *
     * @param entityName the name of the destination entity
     * @param delay      how long from the current simulation time the event
     * should be sent.
     * If delay is a negative number, then it will be
     * changed to 0
     * @param cloudSimTag an user-defined number representing the type of
     * an event/message
     *
     * @pre entityName != null
     * @pre delay >= 0.0
     * @post $none
     */
    protected void sendNow(String entityName, int cloudSimTag) {
        send(entityName, 0, cloudSimTag, null);
    }

    /**
     * Gets the network delay associated to the sent of a message from
     * a given source to a given destination.
     *
     * @param src source of the message
     * @param dst destination of the message
     *
     * @return delay to send a message from src to dst
     *
     * @pre src >= 0
     * @pre dst >= 0
     */
    private double getNetworkDelay(int src, int dst) {
        if (NetworkTopology.isNetworkEnabled()) {
            return NetworkTopology.getDelay(src, dst);
        }
        return 0.0;
    }
}