pads:gaia-apis
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
pads:gaia-apis [2010/11/10 13:02] – gdangelo | pads:gaia-apis [2010/11/10 13:18] – gdangelo | ||
---|---|---|---|
Line 27: | Line 27: | ||
</ | </ | ||
- | ==== GAIA_Initialize() | + | |
+ | ==== Simulation Management ==== | ||
+ | |||
+ | |||
+ | === GAIA_Initialize() | ||
<code java> | <code java> | ||
int | int | ||
Line 53: | Line 57: | ||
- | ==== GAIA_Finalize() | + | === GAIA_Finalize() |
<code java> | <code java> | ||
void GAIA_Finalize ( ); | void GAIA_Finalize ( ); | ||
Line 75: | Line 79: | ||
- | ==== GAIA_SetFstID() | + | === GAIA_SetFstID() |
<code java> | <code java> | ||
void GAIA_SetFstID (int first_id); | void GAIA_SetFstID (int first_id); | ||
Line 97: | Line 101: | ||
- | ==== | + | === |
<code java> | <code java> | ||
- | void GAIA_SetCountDown | + | double |
</ | </ | ||
**Parameters**: | **Parameters**: | ||
- | * int **events**: interval of events before a new evaluation of the heuristic. | + | |
+ | //none// | ||
**Description**: | **Description**: | ||
- | The migration heuristic 3 (MIGR_E3) is based on the events history but differently from MIGR_E2 it is triggered only after a given number of events | + | Returns |
**Notes**: | **Notes**: | ||
- | The default value of E3_EVENT_COUNTDOWN is 30 events. | + | //none// |
**Return value:** | **Return value:** | ||
- | //none// | + | The time-step length (double). |
- | ==== | + | === |
<code java> | <code java> | ||
- | void GAIA_SetMT | + | int |
</ | </ | ||
**Parameters**: | **Parameters**: | ||
- | * int **new_size**: it defines | + | |
+ | * int **migrable**: MIGRABLE if the SE can be migrated, NOT_MIGRABLE if the SE can not be relocated; | ||
**Description**: | **Description**: | ||
- | The Migration Threshold (MT) is a value used to limit the migration rate of SEs. Each SE can evaluate | + | This API is used to register a SE, the runtime returns |
- | + | ||
- | + | ||
- | ^ Migration heuristic | + | |
- | | MIGR_OFF | + | |
- | | MIGR_ON / MIGR_E1 | + | |
- | | MIGR_E2 | + | |
- | + | ||
- | \\ | + | |
**Notes**: | **Notes**: | ||
- | Some degree | + | The registration |
**Return value:** | **Return value:** | ||
- | //none// | + | The descriptor (integer) of the SE. |
- | ==== | + | === |
<code java> | <code java> | ||
- | void GAIA_SetMF | + | double |
</ | </ | ||
**Parameters**: | **Parameters**: | ||
- | * float **migr_factor**: | + | |
+ | //none// | ||
**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 | + | It is used by the LP to notify to the runtime that the current timestep is ended, and therefore, the local LP is ready to start the next timestep. The LP will remain blocked until the runtime will enable |
**Notes**: | **Notes**: | ||
- | The number of migrations is a trade-off between a high LCR and the overhead due to migrations. | + | //none// |
**Return value:** | **Return value:** | ||
- | //none// | + | Returns the next timestep value (double). |
+ | |||
+ | |||
+ | ==== Migration ==== | ||
- | ==== | + | === |
<code java> | <code java> | ||
- | void | + | void |
</ | </ | ||
**Parameters**: | **Parameters**: | ||
- | * int **history_slots**: number | + | * int **id**: Identifier |
+ | * String **data**: A string containing the internal state of the SE; | ||
+ | * int **size**: String size; | ||
**Description**: | **Description**: | ||
- | The migration | + | 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 |
**Notes**: | **Notes**: | ||
- | Too many slots would reduce | + | * The " |
+ | |||
+ | * The GAIA_Migrate() is implemented using a " | ||
**Return value:** | **Return value:** | ||
Line 191: | Line 196: | ||
- | ==== | + | === |
<code java> | <code java> | ||
- | void | + | void |
</ | </ | ||
**Parameters**: | **Parameters**: | ||
- | * int **size**: number | + | * int **id**: Identifier |
+ | * byte[] **data**: A byte-array containing the internal state of the SE; | ||
+ | * int **size**: String size; | ||
**Description**: | **Description**: | ||
- | The migration | + | 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 |
**Notes**: | **Notes**: | ||
- | //none// | + | * The " |
+ | |||
+ | * 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:** | **Return value:** | ||
Line 211: | Line 223: | ||
//none// | //none// | ||
- | ==== | + | |
+ | === | ||
<code java> | <code java> | ||
- | void | + | void |
</ | </ | ||
**Parameters**: | **Parameters**: | ||
- | * int **state**: it selects | + | * int **events**: interval of events before a new evaluation of the heuristic. |
**Description**: | **Description**: | ||
- | All the implemented | + | The migration |
- | ^ Migration heuristic | + | **Notes**: |
- | | MIGR_OFF | + | |
- | | MIGR_ON / MIGR_E1 | + | |
- | | MIGR_E2 | + | |
- | | MIGR_E3 | + | |
- | \\ | + | The default value of E3_EVENT_COUNTDOWN is 30 events. |
- | |||
- | **Notes**: | ||
- | |||
- | For tuning of the heuristics please see: | ||
- | * GAIA_SetMT(): | ||
- | * GAIA_SetMF(): | ||
- | * E2_EVENT_HISTORY_SIZE, | ||
- | * E3_EVENT_COUNTDOWN, | ||
- | * HISTORY_SLOTS, | ||
**Return value:** | **Return value:** | ||
Line 245: | Line 245: | ||
//none// | //none// | ||
- | ==== | + | |
+ | === | ||
<code java> | <code java> | ||
- | void | + | void |
</ | </ | ||
**Parameters**: | **Parameters**: | ||
- | * int **state**: it turns ON and OFF the load balancing mechanism provided by GAIA+, {LOAD_ON, LOAD_OFF}, default LOAD_OFF; | + | * int **new_size**: it defines |
**Description**: | **Description**: | ||
- | The GAIA+ mechanism automatically reacts to heterogeneous hardware | + | The Migration Threshold |
+ | |||
+ | |||
+ | ^ Migration heuristic | ||
+ | | MIGR_OFF | ||
+ | | MIGR_ON / MIGR_E1 | ||
+ | | MIGR_E2 | ||
+ | |||
+ | \\ | ||
**Notes**: | **Notes**: | ||
- | //none// | + | Some degree of randomization is included in the mechanism to reduce the "wave effects" |
**Return value:** | **Return value:** | ||
Line 266: | Line 276: | ||
- | ==== | + | === |
<code java> | <code java> | ||
- | double | + | void GAIA_SetMF |
</ | </ | ||
**Parameters**: | **Parameters**: | ||
- | + | * float **migr_factor**: | |
- | //none// | + | |
**Description**: | **Description**: | ||
- | Returns | + | All the implemented migration heuristics are based on the evaluation |
**Notes**: | **Notes**: | ||
- | //none// | + | The number of migrations is a trade-off between a high LCR and the overhead due to migrations. |
**Return value:** | **Return value:** | ||
- | The time-step length (double). | + | //none// |
- | ==== | + | === |
<code java> | <code java> | ||
- | int | + | void GAIA_SetHistorySlots |
</ | </ | ||
**Parameters**: | **Parameters**: | ||
- | + | * int **history_slots**: number of slots considered in the history matrix; | |
- | * int **migrable**: MIGRABLE if the SE can be migrated, NOT_MIGRABLE if the SE can not be relocated; | + | |
**Description**: | **Description**: | ||
- | This API is used to register a SE, the runtime returns a descriptor that will be used to identify the SE. The registration of a SE is required | + | The migration heuristic 1 (MIGR_ON / MIGR_E1) uses a sliding window mechanism |
**Notes**: | **Notes**: | ||
- | The registration | + | Too many slots would reduce the reactivity |
**Return value:** | **Return value:** | ||
- | The descriptor (integer) of the SE. | + | //none// |
- | ==== | + | === |
<code java> | <code java> | ||
- | double | + | void GAIA_SetEventHistorySize |
</ | </ | ||
**Parameters**: | **Parameters**: | ||
- | + | * int **size**: number of events (FIFO order) considered by the migration heuristic 2 and 3. | |
- | //none// | + | |
**Description**: | **Description**: | ||
- | It is used by the LP to notify to the runtime that the current timestep is ended, and therefore, the local LP is ready to start the next timestep. The LP will remain blocked until the runtime will enable | + | 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 |
**Notes**: | **Notes**: | ||
Line 329: | Line 336: | ||
**Return value:** | **Return value:** | ||
- | Returns the next timestep value (double). | + | //none// |
- | + | === | |
- | ==== | + | |
<code java> | <code java> | ||
- | void | + | void |
</ | </ | ||
**Parameters**: | **Parameters**: | ||
- | * int **id**: Identifier of the migrating SE; | + | * int **state**: it selects |
- | * String **data**: A string containing the internal state of the SE; | + | |
- | * int **size**: String size; | + | |
**Description**: | **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, | + | All the implemented |
- | **Notes**: | + | ^ Migration heuristic |
+ | | MIGR_OFF | ||
+ | | MIGR_ON / MIGR_E1 | ||
+ | | MIGR_E2 | ||
+ | | MIGR_E3 | ||
- | * The " | + | \\ |
- | * The GAIA_Migrate() is implemented using a " | + | |
+ | **Notes**: | ||
+ | |||
+ | For tuning of the heuristics please see: | ||
+ | * GAIA_SetMT(): for an introduction to the Migration Threshold, that is a mechanism that reduces the migration rate of SEs; | ||
+ | * GAIA_SetMF(): | ||
+ | * E2_EVENT_HISTORY_SIZE, | ||
+ | * E3_EVENT_COUNTDOWN, | ||
+ | * HISTORY_SLOTS, | ||
**Return value:** | **Return value:** | ||
Line 357: | Line 372: | ||
//none// | //none// | ||
+ | ==== Load Balancing ==== | ||
- | ==== | + | === |
<code java> | <code java> | ||
- | void | + | void |
</ | </ | ||
**Parameters**: | **Parameters**: | ||
- | * int **id**: Identifier of the migrating SE; | + | * int **state**: it turns ON and OFF the load balancing mechanism provided by GAIA+, {LOAD_ON, LOAD_OFF}, default LOAD_OFF; |
- | * byte[] **data**: A byte-array containing the internal state of the SE; | + | |
- | * int **size**: String size; | + | |
**Description**: | **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 GAIA+ mechanism automatically reacts |
**Notes**: | **Notes**: | ||
- | * The " | + | //none// |
- | + | ||
- | * 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:** | **Return value:** | ||
Line 386: | Line 395: | ||
- | ==== GAIA_Send() | + | ==== Communication |
+ | |||
+ | === 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 412: | Line 423: | ||
- | ==== 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 441: | Line 452: | ||
- | ==== 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 468: | Line 479: | ||
- | ==== 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 498: | Line 509: | ||
- | ==== GAIA_Receive() | + | === GAIA_Receive() |
<code java> | <code java> | ||
String | String | ||
Line 527: | Line 538: | ||
- | ==== GAIA_ByteReceive() | + | === GAIA_ByteReceive() |
<code java> | <code java> | ||
byte[] | byte[] | ||
Line 556: | Line 567: | ||
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(); |
pads/gaia-apis.txt · Last modified: 2017/12/20 07:48 by gdangelo