1 /* transport - low level communication (send/receive bunches of bytes) */
2 /* module's public interface exported to end user. */
4 /* Copyright (c) 2004, 2005, 2006, 2007, 2009, 2010. The SimGrid Team.
5 * All rights reserved. */
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. */
15 /** \addtogroup XBT_sock
16 * \brief Socket handling
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.
23 * The main difference is that you cannot exchange arbitrary bytes on
24 * sockets, but messages. See the \ref GRAS_msg section for details.
26 * If you need an example of how to use sockets, check \ref GRAS_ex_ping.
29 /** \defgroup XBT_sock_create Socket creation functions
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;
38 XBT_PUBLIC(void) xbt_socket_new(int incoming, xbt_socket_t* dst);
39 XBT_PUBLIC(void) xbt_socket_new_ext(int incoming,
41 xbt_trp_plugin_t plugin,
42 unsigned long int buf_size,
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);
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,
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);
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,
57 unsigned long int bufSize,
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,
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);
67 XBT_PUBLIC(void) xbt_socket_close(xbt_socket_t sd);
68 XBT_PUBLIC(void) xbt_socket_close_voidp(void *sock);
71 /** \defgroup XBT_sock_info Retrieving data about sockets and peers
74 * Who are you talking to?
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);
81 /** @brief Get the port number on which this socket is connected on remote side
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.
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
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);
101 /** \defgroup XBT_sock_meas Using measurement sockets
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.
107 * You can only use those functions on sockets opened with the "measurement" boolean set to true.
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);
126 *** Main user functions
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,
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);
134 /* Find which socket needs to be read next */
135 XBT_PUBLIC(xbt_socket_t) xbt_trp_select(double timeout);
137 /* Set the peer process name (used by messaging layer) */
138 XBT_PUBLIC(void) xbt_socket_peer_proc_set(xbt_socket_t sock,
141 /** \defgroup XBT_sock_plugin Plugin mechanism
144 * XBT provides a TCP plugin that implements TCP sockets.
145 * You can also write your own plugin if you need another socket
152 struct s_xbt_trp_plugin {
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);
161 xbt_socket_t (*socket_accept) (xbt_socket_t from);
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);
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);
174 /* send/recv may be buffered */
175 void (*send) (xbt_socket_t sd,
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);
185 /* flush has to make sure that the pending communications are achieved */
186 void (*flush) (xbt_socket_t sd);
188 void *data; /* plugin-specific data */
190 /* exit is responsible for freeing data and telling to the OS that
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);
197 typedef void (*xbt_trp_setup_t) (xbt_trp_plugin_t dst);
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);
205 #endif /* XBT_SOCKET_H */