Assert where FATAL error is expected. Don't return arbitrary error code from

user callback. Updated doc.

lib/includes/spdylay/spdylay.h

@@ -346,16 +346,32 @@ typedef struct {
 } spdylay_session_callbacks;
 
 /*
- * Initializes |*session_ptr| for client use. This function returns 0
+ * Initializes |*session_ptr| for client use. The all members of
- * if it succeeds, or negative error code.
+ * |callbacks| are copied to |*session_ptr|. Therefore |*session_ptr|
+ * does not store |callbacks|. |user_data| is an arbitrary user
+ * supplied data, which will be passed to the callback functions.
+ *
+ * This function returns 0 if it succeeds, or one of the following
+ * negative error codes:
+ *
+ * SPDYLAY_ERR_NOMEM
+ *     Out of memory.
  */
 int spdylay_session_client_new(spdylay_session **session_ptr,
                                const spdylay_session_callbacks *callbacks,
                                void *user_data);
 
 /*
- * Initializes |*session_ptr| for server use. This function returns 0
+ * Initializes |*session_ptr| for server use. The all members of
- * if it succeeds, or negative error code.
+ * |callbacks| are copied to |*session_ptr|. Therefore |*session_ptr|
+ * does not store |callbacks|. |user_data| is an arbitrary user
+ * supplied data, which will be passed to the callback functions.
+ *
+ * This function returns 0 if it succeeds, or one of the following
+ * negative error codes:
+ *
+ * SPDYLAY_ERR_NOMEM
+ *     Out of memory.
  */
 int spdylay_session_server_new(spdylay_session **session_ptr,
                                const spdylay_session_callbacks *callbacks,
@@ -367,32 +383,48 @@ int spdylay_session_server_new(spdylay_session **session_ptr,
 void spdylay_session_del(spdylay_session *session);
 
 /*
- * Sends pending frames to the remote peer. This function returns 0 if
+ * Sends pending frames to the remote peer.
- * it succeeds, or negative error code.
+ *
+ * This function returns 0 if it succeeds, or one of the following
+ * negative error codes:
+ *
+ * SPDYLAY_ERR_NOMEM
+ *     Out of memory.
+ * SPDYLAY_ERR_CALLBACK_FAILURE
+ *     The callback function failed.
  */
 int spdylay_session_send(spdylay_session *session);
 
 /*
- * Receives frames from the remote peer. This function returns 0 if it
+ * Receives frames from the remote peer.
- * succeeds, or negative error code.
+ *
+ * This function returns 0 if it succeeds, or one of the following
+ * negative error codes:
+ *
+ * SPDYLAY_ERR_EOF
+ *     The remote peer did shutdown on the connection.
+ * SPDYLAY_ERR_NOMEM
+ *     Out of memory.
+ * SPDYLAY_ERR_CALLBACK_FAILURE
+ *     The callback function failed.
  */
 int spdylay_session_recv(spdylay_session *session);
 
 /*
- * Returns non-zero value if |session| want to receive data from the
+ * Returns nonzero value if |session| want to receive data from the
- * remote peer, or 0.
+ * remote peer.
  *
- * if both spdylay_session_want_read() and
+ * If both spdylay_session_want_read() and
  * spdylay_session_want_write() return 0, the application should drop
  * the connection.
  */
 int spdylay_session_want_read(spdylay_session *session);
 
 /*
- * Returns non-zero value if |session| want to send data to the remote
+ * Returns nonzero value if |session| want to send data to the remote
  * peer, or 0.
  *
- * if both spdylay_session_want_read() and
+ * If both spdylay_session_want_read() and
  * spdylay_session_want_write() return 0, the application should drop
  * the connection.
  */
@@ -441,7 +473,13 @@ void* spdylay_session_get_stream_user_data(spdylay_session *session,
  * |stream_user_data|, the application can easily identifies stream ID
  * for the request.
  *
- * This function returns 0 if it succeeds, or negative error code.
+ * This function returns 0 if it succeeds, or one of the following
+ * negative error codes:
+ *
+ * SPDYLAY_ERR_INVALID_FRAME
+ *     |pri| is invalid.
+ * SPDYLAY_ERR_NOMEM
+ *     Out of memory.
  */
 int spdylay_submit_request(spdylay_session *session, uint8_t pri,
                            const char **nv,
@@ -463,7 +501,11 @@ int spdylay_submit_request(spdylay_session *session, uint8_t pri,
  * subsequent DATA frames. If |data_prd| is NULL, SYN_REPLY will have
  * FLAG_FIN.
  *
- * This function returns 0 if it succeeds, or negative error code.
+ * This function returns 0 if it succeeds, or one of the following
+ * negative error codes:
+ *
+ * SPDYLAY_ERR_NOMEM
+ *     Out of memory.
  */
 int spdylay_submit_response(spdylay_session *session,
                             int32_t stream_id, const char **nv,
@@ -475,28 +517,47 @@ int spdylay_submit_response(spdylay_session *session,
  * data, 1 or more DATA frames will be sent.  If |flags| contains
  * SPDYLAY_FLAG_FIN, the last DATA frame has FLAG_FIN set.
  *
- * This function returns 0 if it succeeds, or negative error code.
+ * This function returns 0 if it succeeds, or one of the following
+ * negative error codes:
+ *
+ * SPDYLAY_ERR_NOMEM
+ *     Out of memory.
  */
 int spdylay_submit_data(spdylay_session *session, int32_t stream_id,
                         uint8_t flags, spdylay_data_provider *data_prd);
 
 /*
  * Submits RST_STREAM frame to cancel/reject stream |stream_id| with
- * status code |status_code|. This function returns 0 if it succeeds,
+ * status code |status_code|.
- * or negative error code.
+ *
+ * This function returns 0 if it succeeds, or one of the following
+ * negative error codes:
+ *
+ * SPDYLAY_ERR_NOMEM
+ *     Out of memory.
  */
 int spdylay_submit_rst_stream(spdylay_session *session, int32_t stream_id,
                               uint32_t status_code);
 
 /*
- * Submits PING frame. This function returns 0 if it succeeds, or
+ * Submits PING frame.
- * negative error code.
+ *
+ * This function returns 0 if it succeeds, or one of the following
+ * negative error codes:
+ *
+ * SPDYLAY_ERR_NOMEM
+ *     Out of memory.
  */
 int spdylay_submit_ping(spdylay_session *session);
 
 /*
- * Submits GOAWAY frame. This function returns 0 if it succeeds, or
+ * Submits GOAWAY frame.
- * negative error code.
+ *
+ * This function returns 0 if it succeeds, or one of the following
+ * negative error codes:
+ *
+ * SPDYLAY_ERR_NOMEM
+ *     Out of memory.
  */
 int spdylay_submit_goaway(spdylay_session *session);
 
@@ -554,8 +615,15 @@ int spdylay_select_next_protocol(unsigned char **out, unsigned char *outlen,
 
 /*
  * Put back previously deferred DATA frame in the stream |stream_id|
- * to outbound queue. This function returns 0 if it succeeds, or
+ * to outbound queue.
- * negative error code.
+ *
+ * This function returns 0 if it succeeds, or one of the following
+ * negative error codes:
+ *
+ * SPDYLAY_ERR_INVALID_ARGUMENT
+ *     The stream does not exist or no deferred data exist.
+ * SPDYLAY_ERR_NOMEM
+ *     Out of memory.
  */
 int spdylay_session_resume_data(spdylay_session *session, int32_t stream_id);
 

lib/spdylay_session.c

@@ -662,6 +662,17 @@ spdylay_outbound_item* spdylay_session_pop_next_ob_item
   }
 }
 
+/*
+ * Called after a frame is sent.
+ *
+ * This function returns 0 if it succeeds, or one of the following
+ * negative error codes:
+ *
+ * SPDYLAY_ERR_NOMEM
+ *     Out of memory.
+ * SPDYLAY_ERR_CALLBACK_FAILURE
+ *     The callback function failed.
+ */
 static int spdylay_session_after_frame_sent(spdylay_session *session)
 {
   /* TODO handle FIN flag. */
@@ -705,6 +716,8 @@ static int spdylay_session_after_frame_sent(spdylay_session *session)
         r = spdylay_submit_data(session, frame->syn_stream.stream_id,
                                 SPDYLAY_FLAG_FIN, aux_data->data_prd);
         if(r != 0) {
+          /* FATAL error */
+          assert(r < SPDYLAY_ERR_FATAL);
           /* TODO If r is not FATAL, we should send RST_STREAM. */
           return r;
         }
@@ -729,6 +742,8 @@ static int spdylay_session_after_frame_sent(spdylay_session *session)
         r = spdylay_submit_data(session, frame->syn_reply.stream_id,
                                 SPDYLAY_FLAG_FIN, data_prd);
         if(r != 0) {
+          /* FATAL error */
+          assert(r < SPDYLAY_ERR_FATAL);
           /* TODO If r is not FATAL, we should send RST_STREAM. */
           return r;
         }
@@ -803,8 +818,10 @@ static int spdylay_session_after_frame_sent(spdylay_session *session)
           session->aob.item = NULL;
           spdylay_active_outbound_item_reset(&session->aob);
         } else if(r < 0) {
+          /* We don't return other error code other than
+             SPDYLAY_ERR_CALLBACK_FAILURE here. */
           spdylay_active_outbound_item_reset(&session->aob);
-          return r;
+          return SPDYLAY_ERR_CALLBACK_FAILURE;
         } else {
           session->aob.framebuflen = r;
           session->aob.framebufoff = 0;
@@ -815,6 +832,8 @@ static int spdylay_session_after_frame_sent(spdylay_session *session)
           session->aob.item = NULL;
           spdylay_active_outbound_item_reset(&session->aob);
         } else {
+          /* FATAL error */
+          assert(r < SPDYLAY_ERR_FATAL);
           spdylay_active_outbound_item_reset(&session->aob);
           return r;
         }
@@ -847,7 +866,7 @@ int spdylay_session_send(spdylay_session *session)
         /* TODO Call error callback? */
         spdylay_outbound_item_free(item);
         free(item);
-        if(framebuflen <= SPDYLAY_ERR_FATAL) {
+        if(framebuflen < SPDYLAY_ERR_FATAL) {
           return framebuflen;
         } else {
           continue;
@@ -870,7 +889,7 @@ int spdylay_session_send(spdylay_session *session)
       if(sentlen == SPDYLAY_ERR_WOULDBLOCK) {
         return 0;
       } else {
-        return sentlen;
+        return SPDYLAY_ERR_CALLBACK_FAILURE;
       }
     } else {
       session->aob.framebufoff += sentlen;
@@ -878,6 +897,8 @@ int spdylay_session_send(spdylay_session *session)
         /* Frame has completely sent */
         r = spdylay_session_after_frame_sent(session);
         if(r < 0) {
+          /* FATAL */
+          assert(r < SPDYLAY_ERR_FATAL);
           return r;
         }
       } else {
@@ -1299,6 +1320,7 @@ static int spdylay_is_non_fatal(int error)
   return error < 0 && error > SPDYLAY_ERR_FATAL;
 }
 
+/* For errors, this function only returns FATAL error. */
 static int spdylay_session_process_ctrl_frame(spdylay_session *session)
 {
   int r = 0;
@@ -1478,6 +1500,7 @@ int spdylay_session_on_data_received(spdylay_session *session,
   return r;
 }
 
+/* For errors, this function only returns FATAL error. */
 static int spdylay_session_process_data_frame(spdylay_session *session)
 {
   uint8_t flags;
@@ -1509,8 +1532,10 @@ int spdylay_session_recv(spdylay_session *session)
         if(r < 0) {
           if(r == SPDYLAY_ERR_WOULDBLOCK) {
             return 0;
-          } else {
+          } else if(r == SPDYLAY_ERR_EOF) {
             return r;
+          } else {
+            return SPDYLAY_ERR_CALLBACK_FAILURE;
           }
         }
         if(spdylay_inbound_buffer_avail(&session->ibuf) < SPDYLAY_HEAD_LEN) {
@@ -1529,6 +1554,8 @@ int spdylay_session_recv(spdylay_session *session)
                                    &session->iframe.bufmax,
                                    session->iframe.len);
         if(r != 0) {
+          /* FATAL */
+          assert(r < SPDYLAY_ERR_FATAL);
           return r;
         }
         session->iframe.off = 0;
@@ -1546,8 +1573,10 @@ int spdylay_session_recv(spdylay_session *session)
         r = spdylay_recv(session);
         if(r == 0 || r == SPDYLAY_ERR_WOULDBLOCK) {
           return 0;
-        } else if(r < 0) {
+        } else if(r == SPDYLAY_ERR_EOF) {
           return r;
+        } else if(r < 0) {
+          return SPDYLAY_ERR_CALLBACK_FAILURE;
         }
       }
       bufavail = spdylay_inbound_buffer_avail(&session->ibuf);
@@ -1579,7 +1608,8 @@ int spdylay_session_recv(spdylay_session *session)
           r = spdylay_session_process_data_frame(session);
         }
         if(r < 0) {
-          /* Fatal error */
+          /* FATAL */
+          assert(r < SPDYLAY_ERR_FATAL);
           return r;
         }
         spdylay_inbound_frame_reset(&session->iframe);