From patchwork Tue Dec 22 15:56:37 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bill Fischofer X-Patchwork-Id: 58936 Delivered-To: patch@linaro.org Received: by 10.112.89.199 with SMTP id bq7csp3320848lbb; Tue, 22 Dec 2015 07:59:48 -0800 (PST) X-Received: by 10.140.177.3 with SMTP id x3mr35484010qhx.82.1450799988722; Tue, 22 Dec 2015 07:59:48 -0800 (PST) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id z71si29897517qka.39.2015.12.22.07.59.47; Tue, 22 Dec 2015 07:59:48 -0800 (PST) Received-SPF: pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) client-ip=54.225.227.206; Authentication-Results: mx.google.com; spf=pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) smtp.mailfrom=lng-odp-bounces@lists.linaro.org; dkim=neutral (body hash did not verify) header.i=@linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id 5333F61737; Tue, 22 Dec 2015 15:59:47 +0000 (UTC) Authentication-Results: lists.linaro.org; dkim=fail reason="verification failed; unprotected key" header.d=linaro.org header.i=@linaro.org header.b=RAT83O84; dkim-adsp=none (unprotected policy); dkim-atps=neutral X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on ip-10-142-244-252 X-Spam-Level: X-Spam-Status: No, score=-2.5 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_LOW,RCVD_IN_MSPIKE_H2,T_DKIM_INVALID,URIBL_BLOCKED autolearn=disabled version=3.4.0 Received: from [127.0.0.1] (localhost [127.0.0.1]) by lists.linaro.org (Postfix) with ESMTP id 569296162C; Tue, 22 Dec 2015 15:59:29 +0000 (UTC) X-Original-To: lng-odp@lists.linaro.org Delivered-To: lng-odp@lists.linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id F0DC361643; Tue, 22 Dec 2015 15:59:23 +0000 (UTC) Received: from mail-oi0-f43.google.com (mail-oi0-f43.google.com [209.85.218.43]) by lists.linaro.org (Postfix) with ESMTPS id B59796162C for ; Tue, 22 Dec 2015 15:56:44 +0000 (UTC) Received: by mail-oi0-f43.google.com with SMTP id o62so105083302oif.3 for ; Tue, 22 Dec 2015 07:56:44 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id; bh=QQUtiQJxNFJVaHJMlDmd9mxCbaY28C8Vk0Z9pXJ9CzY=; b=RAT83O84y64940Tv5fh8ZFTs+6sFVp2JwNZUH0gWIVA0co+/1xOTwumCxriQ/bAiTN 5RYIq2Vu6BjyIqR0Ryy8Q4Amm35DimDY3OsFGTrZQniWE/OZQnEmoOMZaQeLhgUEyD8t sT3sDQ52+uBQu7jxlNTRoUH6gPNoFxDPNj9Uc= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=QQUtiQJxNFJVaHJMlDmd9mxCbaY28C8Vk0Z9pXJ9CzY=; b=T8vXkWp9TCc3Xbo7gURBlFlwPlH/ILX+T90TIQR+js1dVe5vNYgFtH/Ix/u3efJgc0 sThY9N1BhJhrHIWEvLHIaoOjV9mtdEEuAqI/tNIBuFWbzv26sSWQktK9y/w25PA23BG0 uQEfvhNsadBlNGmOd5h7BKxD5gf5GfjtOyZ22SSw4zpw81XdcrJXZXmuJ++355DQQxp9 rqazg5MjJFwhDBbSts12MbGjGEv6hhLyNc+kST3bbRenC1X16oolLUPLfIj/+koF85HA brBl5OHSAtHTjIWMMIBDob4xIUCgC3bWWnCCWeFClf2im6jxxbFxeWboI/3cdLoA2mJT l5ng== X-Gm-Message-State: ALoCoQnWZDJ9LJeQafSd3SAabsgqNak4ndmWMSsAPIbdIX5fOFwfP62BbFEGmZfewgyKfoP5lmLNC2K4U1TUyUnREmXc1O+TYQ== X-Received: by 10.202.185.66 with SMTP id j63mr10898175oif.13.1450799804177; Tue, 22 Dec 2015 07:56:44 -0800 (PST) Received: from Ubuntu15.localdomain (cpe-66-68-129-43.austin.res.rr.com. [66.68.129.43]) by smtp.gmail.com with ESMTPSA id kw1sm6513399obb.28.2015.12.22.07.56.43 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Tue, 22 Dec 2015 07:56:43 -0800 (PST) From: Bill Fischofer To: lng-odp@lists.linaro.org Date: Tue, 22 Dec 2015 09:56:37 -0600 Message-Id: <1450799798-26458-1-git-send-email-bill.fischofer@linaro.org> X-Mailer: git-send-email 2.5.0 X-Topics: patch Subject: [lng-odp] [API-NEXT PATCH 1/2] api: schedule: clarify scheduler API documentation X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: "The OpenDataPlane \(ODP\) List" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" Signed-off-by: Bill Fischofer --- 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. * * @param from Output parameter for the source queue (where the event was * dequeued from). Ignored if NULL.