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