> -----Original Message----- > From: lng-odp [mailto:lng-odp-boun...@lists.linaro.org] On Behalf Of ext > Zoltan Kiss > Sent: Friday, June 05, 2015 8:51 PM > To: lng-odp@lists.linaro.org > Subject: [lng-odp] [API-NEXT PATCH v3 1/9] api: packet_io: clarify what > happens when not all packets are sent > > Currently our examples are not handling this situation as well.
Not much information for the log entry. Something like this "Clarify that the user owns all events not sent/enqueued successfully" would be better > > Signed-off-by: Zoltan Kiss <zoltan.k...@linaro.org> > --- > include/odp/api/packet_io.h | 4 +++- > include/odp/api/queue.h | 7 +++++-- > 2 files changed, 8 insertions(+), 3 deletions(-) > > diff --git a/include/odp/api/packet_io.h b/include/odp/api/packet_io.h > index 89356a6..5a71e52 100644 > --- a/include/odp/api/packet_io.h > +++ b/include/odp/api/packet_io.h > @@ -111,7 +111,9 @@ int odp_pktio_recv(odp_pktio_t pktio, odp_packet_t > pkt_table[], int len); > * @param pkt_table[] Array of packets to send > * @param len length of pkt_table[] > * > - * @return Number of packets sent > + * @return Number of packets sent. If it is less than 'len', the > remaining > + * packets at the end of pkt_table[] are not consumed, and caller has to > take > + * care of them. > * @retval <0 on failure > */ I think that documentation in @param/@return/@retval should be compact. The actual documentation body text is better place to describe what the function does, what are the pre- and post-conditions, user responsibilities, etc So, for example: /** * Send packets * * Sends out a number of packets. A successful call returns the actual number of * packets sent. If return value is less than 'len', the remaining packets at * the end of pkt_table[] are not consumed, and the caller has to take care of them. * * @param pktio Packet IO handle * @param pkt_table[] Array of packets to send * @param len length of pkt_table[] * * @return Number of packets sent * @retval <0 on failure */ int odp_pktio_send(odp_pktio_t pktio, odp_packet_t pkt_table[], int len); > int odp_pktio_send(odp_pktio_t pktio, odp_packet_t pkt_table[], int len); > diff --git a/include/odp/api/queue.h b/include/odp/api/queue.h > index 6a8b15f..ac4147d 100644 > --- a/include/odp/api/queue.h > +++ b/include/odp/api/queue.h > @@ -242,7 +242,8 @@ void *odp_queue_get_context(odp_queue_t queue); > * @param ev Event handle > * > * @retval 0 on success > - * @retval <0 on failure (e.g. queue full) > + * @retval <0 on failure (e.g. queue full), the event is not consumed, > caller > + * has to take care of it. > */ > int odp_queue_enq(odp_queue_t queue, odp_event_t ev); Same comment. In addition (while editing it) "(e.g. queue full)" should be deleted, since all implementations may not be able catch (efficiently) queue overruns on enqueue time. > > @@ -253,7 +254,9 @@ int odp_queue_enq(odp_queue_t queue, odp_event_t ev); > * @param[in] events Array of event handles > * @param num Number of event handles to enqueue > * > - * @return Number of events actually enqueued (0 ... num) > + * @return Number of events actually enqueued (0 ... num). If it is less > than > + * 'num', the remaining events at the end of events[] are not consumed, > and > + * caller has to take care of them. > * @retval <0 on failure > */ > int odp_queue_enq_multi(odp_queue_t queue, const odp_event_t events[], > int num); Same thing. Add text into body, not in @return. -Petri _______________________________________________ lng-odp mailing list lng-odp@lists.linaro.org https://lists.linaro.org/mailman/listinfo/lng-odp
