include/amok/peermanagement.h

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