| Message ID | 1450799798-26458-1-git-send-email-bill.fischofer@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
On Wed, Dec 23, 2015 at 3:07 AM, Savolainen, Petri (Nokia - FI/Espoo) < petri.savolainen@nokia.com> wrote: > > > > -----Original Message----- > > From: lng-odp [mailto:lng-odp-bounces@lists.linaro.org] On Behalf Of EXT > > Bill Fischofer > > Sent: Tuesday, December 22, 2015 5:57 PM > > To: lng-odp@lists.linaro.org > > Subject: [lng-odp] [API-NEXT PATCH 1/2] api: schedule: clarify scheduler > > API documentation > > > > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> > > --- > > include/odp/api/schedule.h | 24 ++++++++++++++++++------ > > 1 file changed, 18 insertions(+), 6 deletions(-) > > > > diff --git a/include/odp/api/schedule.h b/include/odp/api/schedule.h > > index 55191f9..92b1d32 100644 > > --- a/include/odp/api/schedule.h > > +++ b/include/odp/api/schedule.h > > @@ -88,27 +88,39 @@ uint64_t odp_schedule_wait_time(uint64_t ns); > > * When returns an event, the thread holds the queue synchronization > > context > > * (atomic or ordered) until the next odp_schedule() or > > odp_schedule_multi() > > * call. The next call implicitly releases the current context and > > potentially > > - * returns with a new context. User can allow early context release > (e.g. > > see > > - * odp_schedule_release_atomic()) for performance optimization. > > + * returns with a new context. User can allow early context release > > (e.g., see > > + * odp_schedule_release_atomic() and odp_schedule_release_ordered()) for > > + * performance optimization. > > * > > * @param from Output parameter for the source queue (where the event > > was > > * dequeued from). Ignored if NULL. > > - * @param wait Minimum time to wait for an event. Waits infinitely, > if > > set to > > - * ODP_SCHED_WAIT. Does not wait, if set to > > ODP_SCHED_NO_WAIT. > > + * @param wait Minimum time to wait for an event. Waits indefinitely > > if set > > + * to ODP_SCHED_WAIT. Does not wait if set to > > ODP_SCHED_WAIT. > > * Use odp_schedule_wait_time() to convert time to other > > wait > > * values. > > * > > * @return Next highest priority event > > * @retval ODP_EVENT_INVALID on timeout and no events available > > * > > - * @see odp_schedule_multi(), odp_schedule_release_atomic() > > + * @see odp_schedule_multi(), odp_schedule_release_atomic(), > > + * odp_schedule_release_ordered() > > */ > > odp_event_t odp_schedule(odp_queue_t *from, uint64_t wait); > > > > /** > > * Schedule multiple events > > * > > - * Like odp_schedule(), but returns multiple events from a queue. > > + * Like odp_schedule(), but returns multiple events from a queue. The > > caller > > + * specifies the maximum number of events it is willing to accept. The > > + * scheduler is under no obligation to return more than a single event > > but > > + * will never return more than the number specified by the caller. The > > return > > + * code specifies the number of events returned and all of these events > > always > > + * originate from the same source queue and share the same scheduler > > + * synchronization context. > > > > > + * Note that the scheduler manages synchronization > > + * contexts only with respect to events scheduled to other callers. If > > + * multiple events are returned from an atomic or ordered queue, it is > > the > > + * caller's responsibility to manage this shared context among the > > returned > > + * events in a meaningful manner. > > This last note is unnecessary and should be removed. The note just makes > it sound harder than it is. This is not a special case, an application > handles these N events as any N other objects (in a batch). > The intent of the note is to clarify the scope of the scheduler's synchronization guarantees. For example, if a caller receives two events from an atomic queue and then decides to process event 2 before it processes event 1 then it's the caller's responsibility to ensure that that makes sense. In the case of ordered queues, it's more complex since each event has its own order whether or not it is batched with other events by odp_schedule_multi(). So even though they share the same context they are still subject to individual ordering considerations. This is one of the reasons why, in linux-generic at least, odp_schedule_multi() never returns more than a single event from an ordered queue--the corner cases can bet gnarly and the performance benefits would be doubtful. It's not an API-level restriction that multiple events from ordered queues can't be returned, however, just one that implementations may decide to add. The reason for the note was in response to some of Nicolas' questions, which suggested clarification was needed here. So I'd like to see us say something regarding this but open to different/clearer phrasing. > > Otherwise, the changes are OK. > > -Petri > > > > * > > * @param from Output parameter for the source queue (where the event > > was > > * dequeued from). Ignored if NULL. > > -- > > 2.5.0 > > > > _______________________________________________ > > lng-odp mailing list > > lng-odp@lists.linaro.org > > https://lists.linaro.org/mailman/listinfo/lng-odp >
OK, I'll reword slightly to reflect this and repost. Thanks. On Mon, Dec 28, 2015 at 3:53 AM, Savolainen, Petri (Nokia - FI/Espoo) < petri.savolainen@nokia.com> wrote: > > > > > *From:* EXT Bill Fischofer [mailto:bill.fischofer@linaro.org] > *Sent:* Wednesday, December 23, 2015 3:43 PM > *To:* Savolainen, Petri (Nokia - FI/Espoo) > *Cc:* lng-odp@lists.linaro.org > *Subject:* Re: [lng-odp] [API-NEXT PATCH 1/2] api: schedule: clarify > scheduler API documentation > > > > > > On Wed, Dec 23, 2015 at 3:07 AM, Savolainen, Petri (Nokia - FI/Espoo) < > petri.savolainen@nokia.com> wrote: > > > > > -----Original Message----- > > From: lng-odp [mailto:lng-odp-bounces@lists.linaro.org] On Behalf Of EXT > > Bill Fischofer > > Sent: Tuesday, December 22, 2015 5:57 PM > > To: lng-odp@lists.linaro.org > > Subject: [lng-odp] [API-NEXT PATCH 1/2] api: schedule: clarify scheduler > > API documentation > > > > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> > > --- > > include/odp/api/schedule.h | 24 ++++++++++++++++++------ > > 1 file changed, 18 insertions(+), 6 deletions(-) > > > > diff --git a/include/odp/api/schedule.h b/include/odp/api/schedule.h > > index 55191f9..92b1d32 100644 > > --- a/include/odp/api/schedule.h > > +++ b/include/odp/api/schedule.h > > @@ -88,27 +88,39 @@ uint64_t odp_schedule_wait_time(uint64_t ns); > > * When returns an event, the thread holds the queue synchronization > > context > > * (atomic or ordered) until the next odp_schedule() or > > odp_schedule_multi() > > * call. The next call implicitly releases the current context and > > potentially > > - * returns with a new context. User can allow early context release > (e.g. > > see > > - * odp_schedule_release_atomic()) for performance optimization. > > + * returns with a new context. User can allow early context release > > (e.g., see > > + * odp_schedule_release_atomic() and odp_schedule_release_ordered()) for > > + * performance optimization. > > * > > * @param from Output parameter for the source queue (where the event > > was > > * dequeued from). Ignored if NULL. > > - * @param wait Minimum time to wait for an event. Waits infinitely, > if > > set to > > - * ODP_SCHED_WAIT. Does not wait, if set to > > ODP_SCHED_NO_WAIT. > > + * @param wait Minimum time to wait for an event. Waits indefinitely > > if set > > + * to ODP_SCHED_WAIT. Does not wait if set to > > ODP_SCHED_WAIT. > > * Use odp_schedule_wait_time() to convert time to other > > wait > > * values. > > * > > * @return Next highest priority event > > * @retval ODP_EVENT_INVALID on timeout and no events available > > * > > - * @see odp_schedule_multi(), odp_schedule_release_atomic() > > + * @see odp_schedule_multi(), odp_schedule_release_atomic(), > > + * odp_schedule_release_ordered() > > */ > > odp_event_t odp_schedule(odp_queue_t *from, uint64_t wait); > > > > /** > > * Schedule multiple events > > * > > - * Like odp_schedule(), but returns multiple events from a queue. > > + * Like odp_schedule(), but returns multiple events from a queue. The > > caller > > + * specifies the maximum number of events it is willing to accept. The > > + * scheduler is under no obligation to return more than a single event > > but > > + * will never return more than the number specified by the caller. The > > return > > + * code specifies the number of events returned and all of these events > > always > > + * originate from the same source queue and share the same scheduler > > + * synchronization context. > > > > + * Note that the scheduler manages synchronization > > + * contexts only with respect to events scheduled to other callers. If > > + * multiple events are returned from an atomic or ordered queue, it is > > the > > + * caller's responsibility to manage this shared context among the > > returned > > + * events in a meaningful manner. > > This last note is unnecessary and should be removed. The note just makes > it sound harder than it is. This is not a special case, an application > handles these N events as any N other objects (in a batch). > > > > The intent of the note is to clarify the scope of the scheduler's > synchronization guarantees. For example, if a caller receives two events > from an atomic queue and then decides to process event 2 before it > processes event 1 then it's the caller's responsibility to ensure that that > makes sense. > > > > In the case of ordered queues, it's more complex since each event has its > own order whether or not it is batched with other events by > odp_schedule_multi(). So even though they share the same context they are > still subject to individual ordering considerations. This is one of the > reasons why, in linux-generic at least, odp_schedule_multi() never returns > more than a single event from an ordered queue--the corner cases can bet > gnarly and the performance benefits would be doubtful. It's not an > API-level restriction that multiple events from ordered queues can't be > returned, however, just one that implementations may decide to add. > > > > The reason for the note was in response to some of Nicolas' questions, > which suggested clarification was needed here. So I'd like to see us say > something regarding this but open to different/clearer phrasing. > > > > > > An ordered queue is needed to guarantee ordering between threads. It’s not > needed for reordering enqueue operations done by a single thread. > > > > For example, if an application > > - receives a batch of three packets > > - drops the last packet > > - adds a new packet between packets 1 and 2 when enqueuing > packets to the destination queue > > > > Output from the destination queue should be: -2, -1, 0, 1, “new”, 2, 4, 5, > 6, … > > > > Ordering of 1, “new” and 2 is maintained in respect to packets from other > threads (-2…0 and 4…6). > > > > If the thread would store 1, 2 and 3, and enqueue -100, -99, -98 (from > storage) instead, the output would be: -2, -1, 0, -100, -99, -98, 4, 5, 6 > > > > So, ODP guarantees (atomic or ordered) context synchronization, but each > thread decides how it utilizes the context (e.g. in which order it > processes a batch). > > > > From API point of view, synchronization guarantees are exactly the same > between odp_schedule() and odp_schedule_multi(). The only difference is > batch processing and it’s no different from e.g. processing a batch of > packets with odp_pktio_recv(). > > > > -Petri > > > > > > > > > > > Otherwise, the changes are OK. > > -Petri > > > > * > > * @param from Output parameter for the source queue (where the event > > was > > * dequeued from). Ignored if NULL. > > -- > > 2.5.0 > > > > _______________________________________________ > > lng-odp mailing list > > lng-odp@lists.linaro.org > > https://lists.linaro.org/mailman/listinfo/lng-odp > > >
diff --git a/include/odp/api/schedule.h b/include/odp/api/schedule.h index 55191f9..92b1d32 100644 --- a/include/odp/api/schedule.h +++ b/include/odp/api/schedule.h @@ -88,27 +88,39 @@ uint64_t odp_schedule_wait_time(uint64_t ns); * When returns an event, the thread holds the queue synchronization context * (atomic or ordered) until the next odp_schedule() or odp_schedule_multi() * call. The next call implicitly releases the current context and potentially - * returns with a new context. User can allow early context release (e.g. see - * odp_schedule_release_atomic()) for performance optimization. + * returns with a new context. User can allow early context release (e.g., see + * odp_schedule_release_atomic() and odp_schedule_release_ordered()) for + * performance optimization. * * @param from Output parameter for the source queue (where the event was * dequeued from). Ignored if NULL. - * @param wait Minimum time to wait for an event. Waits infinitely, if set to - * ODP_SCHED_WAIT. Does not wait, if set to ODP_SCHED_NO_WAIT. + * @param wait Minimum time to wait for an event. Waits indefinitely if set + * to ODP_SCHED_WAIT. Does not wait if set to ODP_SCHED_WAIT. * Use odp_schedule_wait_time() to convert time to other wait * values. * * @return Next highest priority event * @retval ODP_EVENT_INVALID on timeout and no events available * - * @see odp_schedule_multi(), odp_schedule_release_atomic() + * @see odp_schedule_multi(), odp_schedule_release_atomic(), + * odp_schedule_release_ordered() */ odp_event_t odp_schedule(odp_queue_t *from, uint64_t wait); /** * Schedule multiple events * - * Like odp_schedule(), but returns multiple events from a queue. + * Like odp_schedule(), but returns multiple events from a queue. The caller + * specifies the maximum number of events it is willing to accept. The + * scheduler is under no obligation to return more than a single event but + * will never return more than the number specified by the caller. The return + * code specifies the number of events returned and all of these events always + * originate from the same source queue and share the same scheduler + * synchronization context. Note that the scheduler manages synchronization + * contexts only with respect to events scheduled to other callers. If + * multiple events are returned from an atomic or ordered queue, it is the + * caller's responsibility to manage this shared context among the returned + * events in a meaningful manner. * * @param from Output parameter for the source queue (where the event was * dequeued from). Ignored if NULL.
Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> --- include/odp/api/schedule.h | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-)