src/gromacs/imd/imdsocket.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2014,2015,2016,2019, by the GROMACS development team, led by
   5  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6  * and including many others, as listed in the AUTHORS file in the
   7  * top-level source directory and at http://www.gromacs.org.
   8  *
   9  * GROMACS is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 2.1
  12  * of the License, or (at your option) any later version.
  13  *
  14  * GROMACS is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with GROMACS; if not, see
  21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23  *
  24  * If you want to redistribute modifications to GROMACS, please
  25  * consider that scientific software is very special. Version
  26  * control is crucial - bugs must be traceable. We will be happy to
  27  * consider code for inclusion in the official distribution, but
  28  * derived work must not be called official GROMACS. Details are found
  29  * in the README & COPYING files - if they are missing, get the
  30  * official version at http://www.gromacs.org.
  31  *
  32  * To help us fund GROMACS development, we humbly ask that you cite
  33  * the research papers on the package. Check out http://www.gromacs.org.
  34  */
  35
  36 /*! \libinternal \file
  37  *
  38  * \brief
  39  * Implements the parts of the vmdsock.h interface needed for IMD communication.
  40  *
  41  * \author Martin Hoefling, Carsten Kutzner <ckutzne@gwdg.de>
  42  *
  43  * For more information, see https://www-s.ks.uiuc.edu/Research/vmd/imd/ for general
  44  * IMD information and https://www-s.ks.uiuc.edu/Research/vmd/imd/code/imdapi.tar.gz
  45  * for the IMD reference implementation and API.
  46  *
  47  * \inlibraryapi
  48  * \ingroup module_imd
  49  */
  50
  51 #ifndef GMX_IMD_IMDSOCKET_H
  52 #define GMX_IMD_IMDSOCKET_H
  53
  54 namespace gmx
  55 {
  56
  57 struct IMDSocket;
  58
  59
  60 /*! \internal
  61  *
  62  * \brief Function to initialize winsock
  63  *
  64  * \returns 0 if successful.
  65  */
  66 int imdsock_winsockinit();
  67
  68 /*! \brief Create an IMD master socket.
  69  *
  70  * \returns  The IMD socket if successful. Otherwise prints an error message and returns NULL.
  71  */
  72 IMDSocket *imdsock_create();
  73
  74 //! Portability wrapper around sleep function
  75 void imd_sleep(unsigned int seconds);
  76
  77
  78 /*! \brief Bind the IMD socket to address and port.
  79  *
  80  * Prints out an error message if unsuccessful.
  81  * If port == 0, bind() assigns a free port automatically.
  82  *
  83  *
  84  * \param sock      The IMD socket.
  85  * \param port      The port to bind to.
  86  *
  87  * \returns 0 if successful.
  88  */
  89 int imdsock_bind(IMDSocket *sock, int port);
  90
  91
  92 /*! \brief Set socket to listening state.
  93  *
  94  * Prints out an error message if unsuccessful.
  95  *
  96  * \param sock      The IMD socket.
  97  *
  98  * \returns 0 if successful.
  99  *
 100  */
 101 int imd_sock_listen(IMDSocket *sock);
 102
 103
 104 /*! \brief Accept incoming connection and redirect to client socket.
 105  *
 106  * Prints out an error message if unsuccessful.
 107  *
 108  * \param sock      The IMD socket.
 109  *
 110  * \returns IMD socket if successful, NULL otherwise.
 111  */
 112 IMDSocket *imdsock_accept(IMDSocket *sock);
 113
 114
 115 /*! \brief Get the port number used for IMD connection.
 116  *
 117  * Prints out an error message if unsuccessful.
 118  *
 119  * \param sock      The IMD socket.
 120  * \param port      The assigned port number.
 121  *
 122  * \returns 0 if successful, an error code otherwise.
 123  */
 124 int imdsock_getport(IMDSocket *sock, int *port);
 125
 126 //! Portability wrapper around system htonl function.
 127 int imd_htonl(int src);
 128
 129 //! Portability wrapper around system ntohl function.
 130 int imd_ntohl(int src);
 131
 132
 133 /*! \brief  Write to socket.
 134  *
 135  *
 136  * \param sock      The IMD socket.
 137  * \param buffer    The data to write.
 138  * \param length    Number of bytes to write.
 139  *
 140  * \returns The number of bytes written, or -1.
 141  */
 142 int imdsock_write(IMDSocket *sock, const char *buffer, int length);
 143
 144
 145 /*! \brief  Read from socket.
 146  *
 147  * \param sock      The IMD socket.
 148  * \param buffer    Buffer to put the read data.
 149  * \param length    Number of bytes to read.
 150  *
 151  * \returns The number of bytes read, or -1 for errors.
 152  */
 153 int imdsock_read(IMDSocket *sock, char *buffer, int length);
 154
 155
 156 /*! \brief Shutdown the socket.
 157  *
 158  * \param sock      The IMD socket.
 159  *
 160  */
 161 void imdsock_shutdown(IMDSocket *sock);
 162
 163
 164 /*! \brief Close the socket and free the sock struct memory.
 165  *
 166  * Writes an error message if unsuccessful.
 167  *
 168  * \param sock      The IMD socket.
 169  *
 170  * \returns 1 on success, or 0 if unsuccessful.
 171  */
 172 int imdsock_destroy(IMDSocket *sock);
 173
 174
 175 /*! \brief Try to read from the socket.
 176  *
 177  * Time out after waiting the interval specified.
 178  * Print an error message if unsuccessful.
 179  *
 180  * \param sock         The IMD socket.
 181  * \param timeoutsec   Time out seconds
 182  * \param timeoutusec  Time out microseconds
 183  *
 184  */
 185 int imdsock_tryread(IMDSocket *sock, int timeoutsec, int timeoutusec);
 186
 187 } // namespace gmx
 188
 189 #endif