.. _server: 



Server
========

The :c:struct:`ymo_server` is a relatively plain, TCP socket server. It
is responsible for binding and listening on the server socket, handling
connections (accepting, closing, and idle disconnects), and is responsible
for sending and receiving raw data over the wire.

Server objects are paired with :ref:`protocols`, which handle higher-level
functions like parsing and domain-specific user-facing functionality. Data
and event notifications are relayed to protocols via a set of
:ref:`protocol callbacks`.

Data is read from the wire into a *single* server-owned read buffer.
From there, it is dispatched to the read handler for a specific
:c:type:`ymo_proto_t`. The protocol is *free to modify the contents of the
receive buffer*, but be aware: *the buffer is considered free for reuse
by the server after the protocol read callback has returned!*

.. admonition:: Info

   For more information on parsing, see :ref:`protocols`.




---------------------------------------------------------------
 Types
---------------------------------------------------------------



.. c:struct:: ymo_server

   Internal structure used to manage a yimmo server. 


   .. code-block:: c
      :caption: Definition
   
      struct ymo_server {
          struct ev_io         w_accept;                           /* EV IO watcher for events on accept socket */
          ymo_ev_io_cb_t       cb_accept;                          /* Actual callback to use for accept. */
          char                 recv_buf[YMO_SERVER_RECV_BUF_SIZE]; /* TODO: configure @ runtime */
          bsat_toq_t           idle_toq;                           /* Used for idle disconnect timeouts */
          ymo_proto_t*         proto;                              /* Primary protocol for this server */
          ymo_server_config_t  config;
          int                  listen_fd; /* Socket for `listen`/`accept` */
          ymo_server_state_t   state;
          size_t               no_conn;
      #if YMO_ENABLE_TLS
          SSL_CTX*             ssl_ctx;        /* Optional SSL context */
      #endif /* YMO_ENABLE_TLS */
          pthread_mutex_t*     accept_mutex;
      };


---------------------------------------------------------------
 Functions
---------------------------------------------------------------



.. c:function:: void ymo_accept_cb(struct ev_loop* loop, struct ev_io* watcher, int revents)

   
   This is the libev accept callback. It is invoked whenever a readiness
   notification is received from libev on the server *listen* socket.



.. c:function:: void ymo_multiproc_accept_cb( struct ev_loop* loop, struct ev_io* watcher, int revents)

   
   This is the libev accept callback used for multi-process accepts (in
   which the listen FD is bound prior to fork).
   
   It is invoked whenever a readiness notification is received from libev on the
   server *listen* socket.
   
   See :c:func:`ymo_server_pre_fork` for more info.



.. c:function:: void ymo_read_cb(struct ev_loop* loop, struct ev_io* watcher, int revents)

   
   This is the libev read callback. It is invoked whenever a readiness
   notification is received from libev on a particular *client connection*
   socket indicating that a read may be performed.



.. c:function:: void ymo_write_cb(struct ev_loop* loop, struct ev_io* watcher, int revents)

   
   This is the libev write callback. It is invoked whenever a readiness
   notification is received from libev on a particular *client connection*
   socket, indicating that a write may be performed.