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/05 13:36] – gdangelo | pads:gaia-apis [2010/11/10 13:23] – gdangelo | ||
---|---|---|---|
Line 27: | Line 27: | ||
</ | </ | ||
- | ==== GAIA_Initialize() | + | |
+ | ==== Simulation Management ==== | ||
+ | |||
+ | |||
+ | === GAIA_Initialize() | ||
<code java> | <code java> | ||
int | int | ||
Line 52: | Line 56: | ||
Returns the LP identifier. | Returns the LP identifier. | ||
+ | ---- | ||
- | ==== GAIA_Finalize() | + | === GAIA_Finalize() |
<code java> | <code java> | ||
void GAIA_Finalize ( ); | void GAIA_Finalize ( ); | ||
Line 73: | Line 78: | ||
//none// | //none// | ||
+ | |||
+ | ---- | ||
- | ==== GAIA_SetFstID() | + | === GAIA_SetFstID() |
<code java> | <code java> | ||
void GAIA_SetFstID (int first_id); | void GAIA_SetFstID (int first_id); | ||
Line 90: | Line 97: | ||
//none// | //none// | ||
+ | |||
+ | ---- | ||
Line 96: | Line 105: | ||
//none// | //none// | ||
+ | ---- | ||
- | ==== | + | |
+ | === | ||
<code java> | <code java> | ||
- | void GAIA_SetMT | + | double |
</ | </ | ||
**Parameters**: | **Parameters**: | ||
- | * int **new_size**: | + | |
+ | //none// | ||
**Description**: | **Description**: | ||
- | The Migration Threshold (MT) is a value used to limit the migration rate of SEs. Each SE can evaluate | + | Returns |
+ | **Notes**: | ||
- | ^ Migration heuristic | + | //none// |
- | | MIGR_OFF | + | |
- | | MIGR_ON / MIGR_E1 | + | |
- | | MIGR_E2 | + | |
- | \\ | + | **Return value:** |
- | **Notes**: | + | The time-step length (double). |
- | Some degree of randomization is included in the mechanism to reduce the "wave effects" | + | ---- |
+ | |||
+ | === GAIA_Register() | ||
+ | <code java> | ||
+ | int | ||
+ | </ | ||
+ | |||
+ | **Parameters**: | ||
+ | |||
+ | * int **migrable**: | ||
+ | |||
+ | **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 to extend the scope of the SE outside the local LP (to the whole simulation). Only after the registration the SE will be able to send and receive messages, furthermore it could be involved in the migration and load balancing mechanisms. | ||
+ | |||
+ | **Notes**: | ||
+ | |||
+ | The registration of a SE is an event that has to be propagated to the whole simulator. Therefore, if the registration of a SE happens at timestep **t**, only starting from timestep **t+1** will be possible to send or receive messages regarding such SE. For example, it is NOT possible to register a new SE at timestep **t** and to immediately send a message from this SE in the same timestep. | ||
**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 **state**: it selects | + | * int **id**: Identifier of the migrating SE; |
+ | * String **data**: A string containing the internal state of the SE; | ||
+ | * int **size**: String size; | ||
**Description**: | **Description**: | ||
- | All the implemented | + | 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, |
- | ^ Migration heuristic | + | **Notes**: |
- | | MIGR_OFF | + | |
- | | MIGR_ON / MIGR_E1 | + | |
- | | MIGR_E2 | + | |
- | \\ | + | * The " |
+ | * The GAIA_Migrate() is implemented using a " | ||
+ | |||
+ | **Return value:** | ||
+ | |||
+ | //none// | ||
+ | |||
+ | |||
+ | === GAIA_ByteMigrate() | ||
+ | <code java> | ||
+ | void GAIA_ByteMigrate (int id, byte[] data, int size); | ||
+ | </ | ||
+ | |||
+ | **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 " | ||
**Notes**: | **Notes**: | ||
- | For tuning of the heuristics please see: | + | * The " |
- | GAIA_SetMT(): | + | |
- | GAIA_SetMF(): | + | |
+ | * 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 179: | Line 237: | ||
//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 **events**: interval of events before a new evaluation of the heuristic. |
**Description**: | **Description**: | ||
- | The GAIA+ mechanism automatically reacts to heterogeneous hardware | + | The migration heuristic 3 (MIGR_E3) is based on the events history but differently |
**Notes**: | **Notes**: | ||
- | The load balancing mechanism can be turned ON **only if** the migration | + | The default value of E3_EVENT_COUNTDOWN |
Line 201: | Line 260: | ||
- | ==== | + | === |
<code java> | <code java> | ||
- | double | + | void GAIA_SetMT |
</ | </ | ||
**Parameters**: | **Parameters**: | ||
- | + | * int **new_size**: | |
- | //none// | + | |
**Description**: | **Description**: | ||
- | Returns | + | The Migration Threshold (MT) is a value used to limit the migration rate of SEs (default value = 10). Each SE can evaluate |
+ | |||
+ | |||
+ | ^ 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:** | ||
- | The time-step length (double). | + | //none// |
- | ==== | + | === |
<code java> | <code java> | ||
- | int | + | void GAIA_SetMF |
</ | </ | ||
**Parameters**: | **Parameters**: | ||
- | + | * float **migr_factor**: it defines | |
- | * 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 | + | All the implemented migration heuristics are based on the evaluation of the outbound UNICAST traffic generated by each Simulated Entity. The migration factor |
**Notes**: | **Notes**: | ||
- | The registration | + | The number |
**Return value:** | **Return value:** | ||
- | The descriptor (integer) of the SE. | + | //none// |
- | ==== | + | === |
<code java> | <code java> | ||
- | double | + | void GAIA_SetHistorySlots |
</ | </ | ||
**Parameters**: | **Parameters**: | ||
+ | * int **history_slots**: | ||
+ | |||
+ | **Description**: | ||
+ | |||
+ | The migration heuristic 1 (MIGR_ON / MIGR_E1) uses a sliding window mechanism to evaluate the communication pattern of each SE (HISTORY_SLOTS, | ||
+ | |||
+ | **Notes**: | ||
+ | |||
+ | Too many slots would reduce the reactivity of the migration mechanism. Conversely, a too small value would cause an excessive number of migrations. | ||
+ | |||
+ | **Return value:** | ||
//none// | //none// | ||
+ | |||
+ | |||
+ | === GAIA_SetEventHistorySize() | ||
+ | <code java> | ||
+ | void GAIA_SetEventHistorySize (int size); | ||
+ | </ | ||
+ | |||
+ | **Parameters**: | ||
+ | * int **size**: number of events (FIFO order) considered by the migration heuristic 2 and 3. | ||
**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 264: | Line 350: | ||
**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 292: | Line 386: | ||
//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 321: | Line 409: | ||
- | ==== 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 347: | Line 437: | ||
- | ==== 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 376: | Line 466: | ||
- | ==== 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 403: | Line 493: | ||
- | ==== 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 433: | Line 523: | ||
- | ==== GAIA_Receive() | + | === GAIA_Receive() |
<code java> | <code java> | ||
String | String | ||
Line 462: | Line 552: | ||
- | ==== GAIA_ByteReceive() | + | === GAIA_ByteReceive() |
<code java> | <code java> | ||
byte[] | byte[] | ||
Line 491: | Line 581: | ||
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 525: | Line 619: | ||
void GAIA_SetHistory (int); | void GAIA_SetHistory (int); | ||
void GAIA_SetMF (float); | void GAIA_SetMF (float); | ||
+ | void GAIA_SetMT (unsigned int); | ||
void GAIA_SetMigration (int); | void GAIA_SetMigration (int); | ||
void GAIA_SetLoadBalancing (int); | void GAIA_SetLoadBalancing (int); | ||
Line 536: | Line 631: | ||
void GAIA_GetStatistics (int *, int *, int *); | void GAIA_GetStatistics (int *, int *, int *); | ||
</ | </ | ||
+ | |||
+ | 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