include/xbt/socket.h

   1 /* transport - low level communication (send/receive bunches of bytes)      */
   2 /* module's public interface exported to end user.                          */
   3
   4 /* Copyright (c) 2004, 2005, 2006, 2007, 2009, 2010. The SimGrid Team.
   5  * 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 XBT_SOCKET_H
  11 #define XBT_SOCKET_H
  12
  13 #include "xbt/misc.h"
  14
  15 /** \addtogroup XBT_sock
  16  *  \brief Socket handling
  17  *
  18  * The model of communications in XBT is very close to the BSD socket one.
  19  * To get two hosts exchanging data, one of them needs to open a
  20  * <i>server</i> socket on which it can listen for incoming messages and the
  21  * other one must connect a <i>client</i> socket onto the server one.
  22  *
  23  * The main difference is that you cannot exchange arbitrary bytes on
  24  * sockets, but messages. See the \ref GRAS_msg section for details.
  25  *
  26  * If you need an example of how to use sockets, check \ref GRAS_ex_ping.
  27  */
  28
  29 /** \defgroup XBT_sock_create Socket creation functions
  30  *  \ingroup XBT_sock
  31  *
  32  */
  33 /* @{*/
  34 /** \brief Opaque type describing a socket */
  35 typedef struct s_xbt_socket *xbt_socket_t;
  36 typedef struct s_xbt_trp_plugin s_xbt_trp_plugin_t, *xbt_trp_plugin_t;
  37
  38 void xbt_socket_new(int incoming,
  39                     xbt_socket_t* dst);
  40 void xbt_socket_new_ext(int incoming,
  41                         xbt_socket_t* dst,
  42                         xbt_trp_plugin_t plugin,
  43                         unsigned long int buf_size,
  44                         int measurement);
  45 XBT_INLINE void* xbt_socket_get_data(xbt_socket_t sock);
  46 XBT_INLINE void xbt_socket_set_data(xbt_socket_t sock, void* data);
  47
  48 /** \brief Simply create a client socket (to speak to a remote host) */
  49 XBT_PUBLIC(xbt_socket_t) xbt_socket_tcp_client(const char *host,
  50                                                unsigned short port);
  51 XBT_PUBLIC(xbt_socket_t) xbt_socket_tcp_client_from_string(const char *host);
  52 /** \brief Simply create a server socket (to ear from remote hosts speaking to you) */
  53 XBT_PUBLIC(xbt_socket_t) xbt_socket_tcp_server(unsigned short port);
  54
  55 /** \brief Create a client socket, full interface to all relevant settings */
  56 XBT_PUBLIC(xbt_socket_t) xbt_socket_tcp_client_ext(const char *host,
  57                                                    unsigned short port,
  58                                                    unsigned long int bufSize,
  59                                                    int measurement);
  60 /** \brief Create a server socket, full interface to all relevant settings */
  61 XBT_PUBLIC(xbt_socket_t) xbt_socket_tcp_server_ext(unsigned short portcp_t,
  62                                                    unsigned long int bufSize,
  63                                                    int measurement);
  64 XBT_PUBLIC(xbt_socket_t)
  65     xbt_socket_tcp_server_range(unsigned short minport, unsigned short maxport,
  66                                 unsigned long int buf_size, int measurement);
  67
  68 XBT_PUBLIC(void) xbt_socket_close(xbt_socket_t sd);
  69 XBT_PUBLIC(void) xbt_socket_close_voidp(void *sock);
  70
  71 /* @}*/
  72 /** \defgroup XBT_sock_info Retrieving data about sockets and peers
  73  *  \ingroup XBT_sock
  74  *
  75  * Who are you talking to?
  76  */
  77 /* @{*/
  78
  79 /** Get the port number on which this socket is connected on my side */
  80 XBT_PUBLIC(int) xbt_socket_my_port(xbt_socket_t sock);
  81
  82 /** @brief Get the port number on which this socket is connected on remote side
  83  *
  84  * This is the port declared on remote side with the
  85  * gras_socket_master() function (if any, or a random number being unique on
  86  * the remote host). If remote used gras_socket_master() more than once, the
  87  * lastly declared number will be used here.
  88  *
  89  * Note to BSD sockets experts: With BSD sockets, the sockaddr
  90  * structure allows you to retrieve the port of the client socket on
  91  * remote side, but it is of no use (from user perspective, it is
  92  * some random number above 6000). That is why XBT sockets differ
  93  * from BSD ones here.
  94  */
  95 XBT_PUBLIC(int) xbt_socket_peer_port(xbt_socket_t sock);
  96 /** Get the host name of the remote side */
  97 XBT_PUBLIC(const char *) xbt_socket_peer_name(xbt_socket_t sock);
  98 /** Get the process name of the remote side */
  99 XBT_PUBLIC(const char *) xbt_socket_peer_proc(xbt_socket_t sock);
 100 /* @}*/
 101
 102 /** \defgroup XBT_sock_meas Using measurement sockets
 103  *  \ingroup XBT_sock
 104  *
 105  * You may want to use sockets not to exchange valuable data (in messages),
 106  * but to conduct some bandwidth measurements and related experiments. If so, try those measurement sockets.
 107  *
 108  * You can only use those functions on sockets opened with the "measurement" boolean set to true.
 109  *
 110  */
 111 /* @{*/
 112
 113 XBT_PUBLIC(int) xbt_socket_is_meas(xbt_socket_t sock);
 114 XBT_PUBLIC(void) xbt_socket_meas_send(xbt_socket_t peer,
 115                                       unsigned int timeout,
 116                                       unsigned long int msgSize,
 117                                       unsigned long int msgAmount);
 118 XBT_PUBLIC(void) xbt_socket_meas_recv(xbt_socket_t peer,
 119                                       unsigned int timeout,
 120                                       unsigned long int msgSize,
 121                                       unsigned long int msgAmount);
 122 XBT_PUBLIC(xbt_socket_t) xbt_socket_meas_accept(xbt_socket_t peer);
 123
 124 /* @}*/
 125
 126 /***
 127  *** Main user functions
 128  ***/
 129 /* stable if we know the storage will keep as is until the next trp_flush */
 130 XBT_PUBLIC(void) xbt_trp_send(xbt_socket_t sd, char *data, long int size,
 131                              int stable);
 132 XBT_PUBLIC(void) xbt_trp_recv(xbt_socket_t sd, char *data, long int size);
 133 XBT_PUBLIC(void) xbt_trp_flush(xbt_socket_t sd);
 134
 135 /* Find which socket needs to be read next */
 136 XBT_PUBLIC(xbt_socket_t) xbt_trp_select(double timeout);
 137
 138 /* Set the peer process name (used by messaging layer) */
 139 XBT_PUBLIC(void) xbt_socket_peer_proc_set(xbt_socket_t sock,
 140                                           char *peer_proc);
 141
 142 /** \defgroup XBT_sock_plugin Plugin mechanism
 143  *  \ingroup XBT_sock
 144  *
 145  * XBT provides a TCP plugin that implements TCP sockets.
 146  * You can also write your own plugin if you need another socket
 147  * implementation.
 148  */
 149 /* @{*/
 150
 151 /* A plugin type */
 152
 153 struct s_xbt_trp_plugin {
 154   char *name;
 155
 156   /* dst pointers are created and initialized with default values
 157      before call to socket_client/server.
 158      Retrieve the info you need from there. */
 159   void (*socket_client) (xbt_trp_plugin_t self, const char *host, int port, xbt_socket_t dst);
 160   void (*socket_server) (xbt_trp_plugin_t self, int port, xbt_socket_t dst);
 161
 162   xbt_socket_t (*socket_accept) (xbt_socket_t from);
 163
 164   /* Getting info about who's speaking */
 165   int (*my_port) (xbt_socket_t sd);
 166   int (*peer_port) (xbt_socket_t sd);
 167   const char* (*peer_name) (xbt_socket_t sd);
 168   const char* (*peer_proc) (xbt_socket_t sd);
 169   void (*peer_proc_set) (xbt_socket_t sd, char* peer_proc);
 170
 171   /* socket_close() is responsible of telling the OS that the socket is over,
 172      but should not free the socket itself (beside the specific part) */
 173   void (*socket_close) (xbt_socket_t sd);
 174
 175   /* send/recv may be buffered */
 176   void (*send) (xbt_socket_t sd,
 177                 const char *data,
 178                 unsigned long int size,
 179                 int stable /* storage will survive until flush */ );
 180   int (*recv) (xbt_socket_t sd, char *data, unsigned long int size);
 181   /* raw_send/raw_recv is never buffered (use it for measurement stuff) */
 182   void (*raw_send) (xbt_socket_t sd,
 183                     const char *data, unsigned long int size);
 184   int (*raw_recv) (xbt_socket_t sd, char *data, unsigned long int size);
 185
 186   /* flush has to make sure that the pending communications are achieved */
 187   void (*flush) (xbt_socket_t sd);
 188
 189   void *data;                   /* plugin-specific data */
 190
 191   /* exit is responsible for freeing data and telling to the OS that
 192      this plugin is gone.
 193      If exit is NULL, data gets brutally freed by the generic interface.
 194      (i.e. an exit function is only needed when data contains pointers) */
 195   void (*exit) (xbt_trp_plugin_t);
 196 };
 197
 198 typedef void (*xbt_trp_setup_t) (xbt_trp_plugin_t dst);
 199
 200 XBT_PUBLIC(void) xbt_trp_plugin_new(const char *name, xbt_trp_setup_t setup);
 201 XBT_PUBLIC(xbt_trp_plugin_t)
 202     xbt_trp_plugin_get_by_name(const char *name);
 203
 204 /* @}*/
 205
 206 #endif                          /* XBT_SOCKET_H */