Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Change the way we specify the sizes of bandwidth tests to be able to send really...
[simgrid.git] / include / amok / peermanagement.h
1 /* $Id$ */
2
3 /* amok peer management - servers main loop and remote peer stopping        */
4
5 /* Copyright (c) 2006 Martin Quinson. All rights reserved.                  */
6
7 /* This program is free software; you can redistribute it and/or modify it
8  * under the terms of the license (GNU LGPL) which comes with this package. */
9
10 #ifndef AMOK_PEER_MANAGEMENT_H
11 #define AMOK_PEER_MANAGEMENT_H
12
13 #include <gras.h>
14
15 /** \addtogroup AMOK_pm
16  *  \brief Managing remote servers
17  * 
18  * This module provide the main loop of servers designed to answer to
19  * callbacks. They can furthermore be stopped remotely.  
20  * 
21  * This module is especially useful to program following the centralized
22  * master/slave architecture. In this architecture, one of the processes
23  * acts as a master dispatching orders to the others, which are called
24  * slaves. 
25   
26  * The source code of the <b>slaves</b> then only consists in:
27  *   - declaring the gras datatypes (see \ref GRAS_dd)
28  *   - declaring the messages (with gras_msgtype_declare() or gras_msgtype_declare_rpc())
29  *   - attaching the right callbacks to the messages (with gras_cb_register())
30  *   - declaring the right repetitive actions (see \ref GRAS_timer)
31  *   - joining the group (with amok_pm_group_join(), so that the master now it)
32  *   - entering the endless loop (with amok_pm_mainloop()). 
33  
34  * The <b>master</b>, on its side, should create declare the datatypes and
35  * messages just like slaves. It should then create a group with
36  * amok_pm_group_new().
37  
38  * Afterward, there is two solutions. 
39  *   - If your master is a deamon which never stops itself (just like regular UNIX daemons), it should: 
40  *      - register the needed callbacks to messages comming from slaves
41  *      - register repetitive actions 
42  *      - entering the main loop.
43  *   - If the master is not a deamon, it should:
44  *      - wait a moment for the slaves registration (using gras_msg_handleall())
45  *      - run its algoritpm. For this, it may call RPC on slaves, or explicitely wait (with gras_msg_wait()) for the answers it expects.
46
47  * \section AMOK_pm_compat Compatibility issues
48  * 
49  * The API described here is as of SimGrid 3.2 and higher. In version 3.1
50  * (where this module were introduced), all functions were named amok_hm_*
51  * This was because the module used to be named HostManagement, but it was
52  * renamed before being released to betterly express its purpose.
53  * Unfortunately, the rename was not done properly before version 3.2.
54  * 
55  * @{
56  */
57
58 /* module handling */
59 XBT_PUBLIC void amok_pm_init(void);
60 XBT_PUBLIC void amok_pm_exit(void);
61
62 XBT_PUBLIC void amok_pm_mainloop(double timeOut);
63
64 XBT_PUBLIC void amok_pm_kill_hp(char *name,int port);
65 XBT_PUBLIC void amok_pm_kill(gras_socket_t buddy);
66 XBT_PUBLIC void amok_pm_kill_sync(gras_socket_t buddy);
67
68 XBT_PUBLIC xbt_dynar_t amok_pm_group_new(const char *group_name);
69 XBT_PUBLIC xbt_dynar_t amok_pm_group_get(gras_socket_t master, const char *group_name);
70
71 XBT_PUBLIC void        amok_pm_group_join(gras_socket_t master, const char *group_name);
72 XBT_PUBLIC void        amok_pm_group_leave(gras_socket_t master, const char *group_name);
73
74
75 XBT_PUBLIC void amok_pm_group_shutdown(const char *group_name);
76 XBT_PUBLIC void amok_pm_group_shutdown_remote(gras_socket_t master, const char *group_name);
77
78
79 /** @} */
80 #endif /* AMOK_peer_MANAGEMENT_H */