Parallel And Distributed Simulation Research Group

User Tools

Site Tools

Trace:
pads:gaia-apis

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
pads:gaia-apis [2010/11/10 13:15] – gdangelopads:gaia-apis [2017/12/20 07:48] (current) – gdangelo
Line 56: Line 56:
 Returns the LP identifier. Returns the LP identifier.
  
 +----
  
 ===  GAIA_Finalize()  === ===  GAIA_Finalize()  ===
Line 77: Line 78:
  
 //none// //none//
 +
 +----
  
  
Line 94: Line 97:
  
 //none// //none//
- 
  
 **Return value:** **Return value:**
  
 //none// //none//
 +
 +----
  
  
Line 112: Line 116:
 **Description**: **Description**:
  
-Returns the length of the time-step used in the simulation. This parameter is initialized using the **GLOBAL_LA** parameters as defined in the file "**channels.txt**". For example, GLOBAL_LA=1 defines a global lookahead (timestep) of 1 time-unit, and GLOBAL_LA=0.01 is to define timesteps with a length of 1/100 of time-unit.+Returns the length of the timestep used in the simulation. This parameter is initialized using the **GLOBAL_LA** parameters as defined in the file "**channels.txt**". For example, GLOBAL_LA=1 defines a global lookahead (timestep) of 1 time-unit, and GLOBAL_LA=0.01 is to define timesteps with a length of 1/100 of time-unit.
  
 **Notes**: **Notes**:
Line 120: Line 124:
 **Return value:** **Return value:**
  
-The time-step length (double).+The timestep length (double). 
 + 
 +----
  
  
Line 143: Line 149:
  
 The descriptor (integer) of the SE. The descriptor (integer) of the SE.
 +
 +----
  
  
Line 165: Line 173:
  
 Returns the next timestep value (double). Returns the next timestep value (double).
 +
 +----
 +
  
  
 ==== Migration ==== ==== Migration ====
 +
 +
 +===  GAIA_Migrate()  ===
 +<code java>
 +void    GAIA_Migrate (int id, String data, int size);
 +</code>
 +
 +**Parameters**:
 +   * int **id**: Identifier of the migrating SE;
 +   * String **data**: A string containing the internal state of the SE;
 +   * int **size**: String size;
 +
 +
 +**Description**:
 +
 +It is used by a local LP to migrate a SE to a remote LP. The local LP is **not** free to define what SEs should be migrated. During the simulation execution, the migration mechanism defines what SEs have to be migrated and informs the LP using a "NOTIF_MIGR" message. The other LPs that are not directly involved in the migration will be informed of the event with a "NOTIF_MIGR_EXT".
 +
 +**Notes**:
 +
 +   * The "NOTIF_MIGR" message and the related migration are **mandatory**. The LPs cannot independently migrate any SE without previously receiving a "NOTIF_MIGR" message. This migration of "notified" SEs have to be done at the end of the timestep in which is received the notification.
 +
 +   * The GAIA_Migrate() is implemented using a "EXEC_MIGR" message. Therefore, the LP that receives a message of this type is receiving a migrating Simulated Entity.
 +
 +**Return value:**
 +
 +//none//
 +
 +----
 +
 +
 +===  GAIA_ByteMigrate()  ===
 +<code java>
 +void    GAIA_ByteMigrate (int id, byte[] data, int size);
 +</code>
 +
 +**Parameters**:
 +   * int **id**: Identifier of the migrating SE;
 +   * byte[] **data**: A byte-array containing the internal state of the SE;
 +   * int **size**: String size;
 +
 +
 +**Description**:
 +
 +It is used by a local LP to migrate a SE to a remote LP. The local LP is **not** free to define what SEs should be migrated. During the simulation execution, the migration mechanism defines what SEs have to be migrated and informs the  LP using a "NOTIF_MIGR" message. The other LPs that are not directly involved in the migration will be informed of the event with a “NOTIF_MIGR_EXT”. 
 +
 +**Notes**:
 +
 +   * The "NOTIF_MIGR" message and the related migration are **mandatory**. The LPs cannot independently migrate any SE without previously receiving a "NOTIF_MIGR" message. This migration of “notified” SEs have to be done at the end of the timestep in which is received the notification. 
 +
 +   * The GAIA_ByteMigrate() is implemented using a “EXEC_MIGR” message. Therefore, the LP that receives a message of this type is receiving a migrating Simulated Entity.
 +
 +   * This API has the exactly the same semantic of GAIA_Migrate(). For performance reasons, in this case the SE state is contained in an array instead of a String.
 +
 +**Return value:**
 +
 +//none//
 +
 +----
 +
  
 ===  GAIA_SetCountDown()  === ===  GAIA_SetCountDown()  ===
Line 184: Line 254:
  
 The default value of E3_EVENT_COUNTDOWN is 30 events. The default value of E3_EVENT_COUNTDOWN is 30 events.
- 
  
 **Return value:** **Return value:**
  
 //none// //none//
 +
 +----
  
  
Line 206: Line 277:
 ^ Migration heuristic      ^  SetHistory() semantic       ^ ^ Migration heuristic      ^  SetHistory() semantic       ^
 | MIGR_OFF    |  //none//     | | MIGR_OFF    |  //none//     |
-| MIGR_ON / MIGR_E1   |   Threshold: number of times-steps (since the last reset)   |+| MIGR_ON / MIGR_E1   |   Threshold: number of timesteps (since the last reset)   |
 | MIGR_E2  |  Threshold: number of UNICAST events generated (since the last reset)  | | MIGR_E2  |  Threshold: number of UNICAST events generated (since the last reset)  |
  
Line 219: Line 290:
  
 //none// //none//
 +
 +----
  
  
Line 231: Line 304:
 **Description**: **Description**:
  
-All the implemented migration heuristics are based on the evaluation of the outbound UNICAST traffic generated by each Simulated Entity. The migration factor is a tuning parameters of the heuristics: a low value would increase the number of migrations, conversely a higher value would reduce the number of migrations (default value = 3). +All the implemented migration heuristics are based on the evaluation of the outbound UNICAST traffic generated by each Simulated Entity. The migration factor is a tuning parameters of the heuristics: a low value would increase the number of migrations, conversely a higher value would reduce the number of migrations (default value = 3).
  
 **Notes**: **Notes**:
Line 240: Line 313:
  
 //none// //none//
 +
 +----
  
  
Line 252: Line 327:
 **Description**: **Description**:
  
-The migration heuristic 1 (MIGR_ON / MIGR_E1) uses a sliding window mechanism to evaluate the communication pattern of each SE (HISTORY_SLOTS, default value = 4). The number of slots composing the sliding windows can be defined at the simulation bootstrap using this API.+The migration heuristic 1 (MIGR_ON / MIGR_E1) uses a sliding window mechanism to evaluate the communication pattern of each SE (HISTORY_SLOTS, default value = 4). The number of slots composing the sliding window can be defined at the simulation bootstrap using this API.
  
 **Notes**: **Notes**:
Line 261: Line 336:
  
 //none// //none//
 +
 +----
  
  
Line 273: Line 350:
 **Description**: **Description**:
  
-The migration heuristics 2 and 3 (MIGR_E2 / MIGR_E3) are based on the a sliding-windows with the last E2_EVENT_HISTORY_SIZE messages sent by the SE (default value 100). The number of events composing the sliding windows can be defined at the simulation bootstrap using this API.+The migration heuristics 2 and 3 (MIGR_E2 / MIGR_E3) are based on the a sliding window with the last E2_EVENT_HISTORY_SIZE messages sent by the SE (default value 100). The number of events composing the sliding window can be defined at the simulation bootstrap using this API.
  
 **Notes**: **Notes**:
Line 282: Line 359:
  
 //none// //none//
 +
 +----
 +
  
 ===  GAIA_SetMigration()  === ===  GAIA_SetMigration()  ===
Line 293: Line 373:
 **Description**: **Description**:
  
-All the implemented migration heuristics are based on the evaluation of the outbound UNICAST traffic generated by each SE (also called events). +All the implemented migration heuristics are based on the evaluation of the outbound UNICAST traffic generated by each SE (also called events).
  
 ^ Migration heuristic      ^  Description       ^  Pros  ^  Cons  ^ ^ Migration heuristic      ^  Description       ^  Pros  ^  Cons  ^
 | MIGR_OFF    |  //none//     |  none  |  none  | | MIGR_OFF    |  //none//     |  none  |  none  |
-| MIGR_ON / MIGR_E1   |  The heuristic is evaluated each time-step. It is based on the last E1_HISTORY_SLOTS timesteps of the simulation. It is implemented a sliding window approach that at each step throws away the oldest events and inserts the more recent ones  |  Very high LCR  \\  Well-suited for communication intensive models  |  In some cases, relevant overhead  |  +| MIGR_ON / MIGR_E1   |  The heuristic is evaluated each timestep. It is based on the last E1_HISTORY_SLOTS timesteps of the simulation. It is implemented a sliding window approach that at each step throws away the oldest events and inserts the more recent ones  |  Very high LCR  \\  Well-suited for communication intensive models  |  In some cases, relevant overhead  |  
-| MIGR_E2  |  The heuristic is evaluated each time-step. It is based on the a sliding-windows with the last E2_EVENT_HISTORY_SIZE messages sent by the SE  |  Well suited for simulatons in which the communication pattern of entities changes frequently   |  In some cases, relevant overhead  | +| MIGR_E2  |  The heuristic is evaluated each timestep. It is based on the a sliding window with the last E2_EVENT_HISTORY_SIZE messages sent by the SE  |  Well suited for simulations in which the communication pattern of entities changes frequently   |  In some cases, relevant overhead  | 
-| MIGR_E3  |  The heuristic is evaluated only if the SE has sent at least E3_EVENT_COUNTDOWN events after the last evaluation. The rest of the mechanism is the same as MIGR_E2  |  Well suited for simulatons with a very high number of SEs and in which the communication pattern of entities changes frequently   |  In some cases slow convergence and slightly lower LCR  |+| MIGR_E3  |  The heuristic is evaluated only if the SE has sent at least E3_EVENT_COUNTDOWN events after the last evaluation. The rest of the mechanism is the same as MIGR_E2  |  Well suited for simulations with a very high number of SEs and in which the communication pattern of entities changes frequently   |  In some cases slow convergence and slightly lower LCR  |
  
 \\ \\
Line 309: Line 389:
   * GAIA_SetMT(): for an introduction to the Migration Threshold, that is a mechanism that reduces the migration rate of SEs;   * GAIA_SetMT(): for an introduction to the Migration Threshold, that is a mechanism that reduces the migration rate of SEs;
   * GAIA_SetMF(): for an introduction to the Migration Factor, that is the parameter that is used to evaluate if and where activate the migration mechanism for a SE;   * GAIA_SetMF(): for an introduction to the Migration Factor, that is the parameter that is used to evaluate if and where activate the migration mechanism for a SE;
 +  * E1_HISTORY_SLOTS, default value = 4. It can be modified in the simulation setup using the GAIA_SetHistorySlots() API.
   * E2_EVENT_HISTORY_SIZE, default value = 100. It is how many events (FIFO order) are considered by migration heuristics 2 and 3. This value can be changed using the GAIA_SetEventHistorySize() API.   * E2_EVENT_HISTORY_SIZE, default value = 100. It is how many events (FIFO order) are considered by migration heuristics 2 and 3. This value can be changed using the GAIA_SetEventHistorySize() API.
   * E3_EVENT_COUNTDOWN, default value = 30. It is the interval of events before a new evaluation of the heuristic. This value can be changed using the GAIA_SetCountDown() API.   * E3_EVENT_COUNTDOWN, default value = 30. It is the interval of events before a new evaluation of the heuristic. This value can be changed using the GAIA_SetCountDown() API.
-  * HISTORY_SLOTS, default value = 4. It can be modified in the simulation setup using the GAIA_SetHistorySlots() API. 
  
 **Return value:** **Return value:**
  
 //none// //none//
 +
 +----
 +
  
 ==== Load Balancing ==== ==== Load Balancing ====
Line 339: Line 422:
 //none// //none//
  
 +----
  
-====  GAIA_Migrate()  ==== 
-<code java> 
-void    GAIA_Migrate (int id, String data, int size); 
-</code> 
- 
-**Parameters**: 
-   * int **id**: Identifier of the migrating SE; 
-   * String **data**: A string containing the internal state of the SE; 
-   * int **size**: String size; 
- 
- 
-**Description**: 
- 
-It is used by a local LP to migrate a SE to a remote LP. The local LP is **not** free to define what SEs should be migrated. During the simulation execution, the migration mechanism defines what SEs have to be migrated and informs the LP using a "NOTIF_MIGR" message. The other LPs that are not directly involved in the migration will be informed of the event with a "NOTIF_MIGR_EXT". 
- 
-**Notes**: 
- 
-   * The "NOTIF_MIGR" message and the related migration are **mandatory**. The LPs cannot independently migrate any SE without previously receiving a "NOTIF_MIGR" message. This migration of "notified" SEs have to be done at the end of the timestep in which is received the notification. 
- 
-   * The GAIA_Migrate() is implemented using a "EXEC_MIGR" message. Therefore, the LP that receives a message of this type is receiving a migrating Simulated Entity. 
- 
-**Return value:** 
- 
-//none// 
- 
- 
-====  GAIA_ByteMigrate()  ==== 
-<code java> 
-void    GAIA_ByteMigrate (int id, byte[] data, int size); 
-</code> 
- 
-**Parameters**: 
-   * int **id**: Identifier of the migrating SE; 
-   * byte[] **data**: A byte-array containing the internal state of the SE; 
-   * int **size**: String size; 
- 
- 
-**Description**: 
- 
-It is used by a local LP to migrate a SE to a remote LP. The local LP is **not** free to define what SEs should be migrated. During the simulation execution, the migration mechanism defines what SEs have to be migrated and informs the  LP using a "NOTIF_MIGR" message. The other LPs that are not directly involved in the migration will be informed of the event with a “NOTIF_MIGR_EXT”.  
- 
-**Notes**: 
- 
-   * The "NOTIF_MIGR" message and the related migration are **mandatory**. The LPs cannot independently migrate any SE without previously receiving a "NOTIF_MIGR" message. This migration of “notified” SEs have to be done at the end of the timestep in which is received the notification.  
- 
-   * The GAIA_ByteMigrate() is implemented using a “EXEC_MIGR” message. Therefore, the LP that receives a message of this type is receiving a migrating Simulated Entity. 
- 
-   * This API has the exactly the same semantic of GAIA_Migrate(). For performance reasons, in this case the SE state is contained in an array instead of a String. 
- 
-**Return value:** 
- 
-//none// 
  
 +====  Communication  ====
  
-====  GAIA_Send()  ====+===  GAIA_Send()  ===
 <code java> <code java>
 void    GAIA_Send (int obj_src, int obj_dest, double Ts, String Msg, int Size); void    GAIA_Send (int obj_src, int obj_dest, double Ts, String Msg, int Size);
Line 413: Line 446:
 **Notes**: **Notes**:
  
-The message time-stamp has to respect the constraints given by the synchronization algorithm (time-stepped).+The message time-stamp has to respect the constraints given by the synchronization algorithm (timestepped).
  
 **Return value:** **Return value:**
Line 419: Line 452:
 //none// //none//
  
 +----
  
-====  GAIA_ByteSend()  ====+ 
 +===  GAIA_ByteSend()  ===
 <code java> <code java>
 void    GAIA_ByteSend (int obj_src, int obj_dest, double Ts, byte[] Msg, int Size); void    GAIA_ByteSend (int obj_src, int obj_dest, double Ts, byte[] Msg, int Size);
Line 439: Line 474:
 **Notes**: **Notes**:
  
-   * The message time-stamp has to respect the constraints given by the synchronization algorithm (time-stepped).+   * The message time-stamp has to respect the constraints given by the synchronization algorithm (timestepped).
  
    * This API has the exactly the same semantic of GAIA_Send(). For performance reasons, in this case the message is contained in an array instead of a String.    * This API has the exactly the same semantic of GAIA_Send(). For performance reasons, in this case the message is contained in an array instead of a String.
Line 448: Line 483:
 //none// //none//
  
 +----
  
-====  GAIA_Broadcast()  ====+ 
 +===  GAIA_Broadcast()  ===
 <code java> <code java>
 void    GAIA_Broadcast (int obj_src, double Ts, String Msg, int Size); void    GAIA_Broadcast (int obj_src, double Ts, String Msg, int Size);
Line 467: Line 504:
 **Notes**: **Notes**:
  
-   * The message time-stamp has to respect the constraints given by the synchronization algorithm (time-stepped).+   * The message time-stamp has to respect the constraints given by the synchronization algorithm (timestepped).
  
    * Given that the message is delivered also to the SE that is originating it, it must be carefully managed to avoid loops.    * Given that the message is delivered also to the SE that is originating it, it must be carefully managed to avoid loops.
Line 474: Line 511:
  
 //none// //none//
 +
 +----
  
  
-====  GAIA_ByteBroadcast()  ====+===  GAIA_ByteBroadcast()  ===
 <code java> <code java>
 void    GAIA_ByteBroadcast (int obj_src, double Ts, byte[] Msg, int Size); void    GAIA_ByteBroadcast (int obj_src, double Ts, byte[] Msg, int Size);
Line 494: Line 533:
 **Notes**: **Notes**:
  
-   * The message time-stamp has to respect the constraints given by the synchronization algorithm (time-stepped).+   * The message time-stamp has to respect the constraints given by the synchronization algorithm (timestepped).
  
    * Given that the message is delivered also to the SE that is originating it, it must be carefully managed to avoid loops.    * Given that the message is delivered also to the SE that is originating it, it must be carefully managed to avoid loops.
Line 505: Line 544:
 //none// //none//
  
 +----
  
-====  GAIA_Receive()  ====+ 
 +===  GAIA_Receive()  ===
 <code java> <code java>
 String  GAIA_Receive(int maxlen); String  GAIA_Receive(int maxlen);
Line 533: Line 574:
 Returns the message (String). Returns the message (String).
  
 +----
  
  
-====  GAIA_ByteReceive()  ====+===  GAIA_ByteReceive()  ===
 <code java> <code java>
 byte[]  GAIA_ByteReceive(int maxlen); byte[]  GAIA_ByteReceive(int maxlen);
Line 564: Line 606:
 Returns the message (byte-array). Returns the message (byte-array).
  
-====  GAIA_GetStatistics()  ====+---- 
 + 
 + 
 +==== Statistics ==== 
 + 
 + 
 +===  GAIA_GetStatistics()  ===
 <code java> <code java>
 void  GAIA_GetStatistics(); void  GAIA_GetStatistics();
Line 589: Line 637:
  
 //none// //none//
 +
 +
 +----
  
 ===== C bindings ===== ===== C bindings =====
Line 599: Line 650:
 void    GAIA_SetMF (float); void    GAIA_SetMF (float);
 void    GAIA_SetMT (unsigned int); void    GAIA_SetMT (unsigned int);
 +void GAIA_SetCountDown ( int );
 +void GAIA_SetHistorySlots (int );
 +void GAIA_SetEventHistorySize (int );
 void    GAIA_SetMigration (int); void    GAIA_SetMigration (int);
 void    GAIA_SetLoadBalancing (int); void    GAIA_SetLoadBalancing (int);
Line 612: Line 666:
  
 Please refer to the description of the Java binding to have an introduction to the provided APIs. Please refer to the description of the Java binding to have an introduction to the provided APIs.
- 
  
pads/gaia-apis.txt · Last modified: 2017/12/20 07:48 by gdangelo
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki