.. _connection: 



Connections
=============




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




.. :c:enum:: `ymo_conn_state_t`

   :YMO_CONN_OPEN: Connection is established.
   :YMO_CONN_CLOSING: Shutdown has been invoked. Waiting for clean close.
   :YMO_CONN_CLOSED: File descriptor has been closed.
   :YMO_CONN_ERROR: Connection is in an error state and being automatically terminated.




.. c:struct:: ymo_conn

   Internal structure used to manage a yimmo conn.


   .. code-block:: c
      :caption: Definition
   
      struct ymo_conn {
          ymo_server_t*     server;          /* Pointer to managing server */
          ymo_proto_t*      proto;           /* Current protocol managing this connection */
          void*             proto_data;      /* Protocol-specific connection data */
          void*             user;            /* User-code per-connection data */
          bsat_toq_t*       toq;             /* HACK HACK: fix cancel for now. */
          bsat_timeout_t    idle_timeout;    /* Used to disconnect idle sessions */
          uuid_t            id;              /* Unique ID */
          int               fd;              /* The underlying file descriptor */
          struct ev_loop*   loop;            /* EV loop that manages this connection. */
          struct ev_io      w_read;          /* Per-connection read watcher */
          struct ev_io      w_write;         /* Per-connection write watcher */
          ymo_conn_state_t  state;           /* Connection state */
      #if YMO_ENABLE_TLS
          SSL*              ssl;             /* Optional SSL connection info */
      #endif /* YMO_ENABLE_TLS */
      #if defined(YMO_CONN_LOCK) && (YMO_CONN_LOCK == 1)
          pthread_mutexattr_t  lattr;        /* Per-connection mutex attributes */
          pthread_mutex_t      lock;         /* Per-connection mutex */
      #endif /* YMO_CONN_LOCK */
      };


.. c:type:: ymo_ev_io_cb_t

   We typedef the callback signature for ev_io_watcher's, purely as
   a matter of convenience.


   .. code-block:: c
      :caption: Definition
   
      typedef void (*ymo_ev_io_cb_t)(
              struct ev_loop* loop,
              struct ev_io* watcher,
              int revents);


.. c:function:: ymo_conn_t* ymo_conn_create( ymo_server_t* server, ymo_proto_t* proto, int client_fd, struct ev_loop* loop, ymo_ev_io_cb_t read_cb, ymo_ev_io_cb_t write_cb)

   Create a new conn object.



.. c:function:: void ymo_conn_start_idle_timeout( ymo_conn_t* conn, bsat_toq_t* idle_toq)

   Start idle disconnect timer for a given conn.



.. c:function:: void ymo_conn_reset_idle_timeout( ymo_conn_t* conn, bsat_toq_t* idle_toq)

   Reset idle disconnect timer for a given conn.



.. c:function:: void ymo_conn_cancel_idle_timeout(ymo_conn_t* conn)

   Cancel idle disconnect timer for a given conn.



.. c:function:: ymo_status_t ymo_conn_transition_proto( ymo_conn_t* conn, ymo_proto_t* proto_new)

   Transition a connection to a new protocol.



.. c:function:: ymo_status_t ymo_conn_send_buckets( ymo_conn_t* conn, ymo_bucket_t** head_p)

   Send buckets over the wire. 



.. c:function:: void ymo_conn_rx_enable(ymo_conn_t* conn, int flag)

   Turn receiving on/off, according to flag (0 = off; 1 = on)



.. c:function:: void ymo_conn_tx_enable(ymo_conn_t* conn, int flag)

   Turn receiving on/off, according to flag (0 = off; 1 = on)



.. c:function:: void ymo_conn_tx_now(ymo_conn_t* conn)

   Trigger the write callback right now, as if ev_run had invoked it.



.. c:function:: void ymo_conn_rx_now(ymo_conn_t* conn)

   Trigger the read callback right now, as if ev_run had invoked it.



.. c:function:: ymo_conn_state_t ymo_conn_close(ymo_conn_t* conn, int clean)

   Close a conn object.
   
   :param conn: The connection to close.
   :param clean: if ``1`` perform a clean close using ``shutdown``. If ``0``, just close the file descriptor.
   :returns: the connection state after invocation.



.. c:function:: void ymo_conn_free(ymo_conn_t* conn)

   Free a conn object.