From patchwork Mon Dec 28 17:10:02 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bill Fischofer X-Patchwork-Id: 59028 Delivered-To: patch@linaro.org Received: by 10.112.130.2 with SMTP id oa2csp1821272lbb; Mon, 28 Dec 2015 09:10:18 -0800 (PST) X-Received: by 10.55.55.72 with SMTP id e69mr71024073qka.42.1451322618489; Mon, 28 Dec 2015 09:10:18 -0800 (PST) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id n36si65511460qgn.11.2015.12.28.09.10.18; Mon, 28 Dec 2015 09:10:18 -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 C942A61712; Mon, 28 Dec 2015 17:10:17 +0000 (UTC) Authentication-Results: lists.linaro.org; dkim=fail reason="verification failed; unprotected key" header.d=linaro.org header.i=@linaro.org header.b=QYTPT/+a; 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_H3, RCVD_IN_MSPIKE_WL, 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 2F73361704; Mon, 28 Dec 2015 17:10:12 +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 61EFD61706; Mon, 28 Dec 2015 17:10:10 +0000 (UTC) Received: from mail-ob0-f177.google.com (mail-ob0-f177.google.com [209.85.214.177]) by lists.linaro.org (Postfix) with ESMTPS id 748D661701 for ; Mon, 28 Dec 2015 17:10:09 +0000 (UTC) Received: by mail-ob0-f177.google.com with SMTP id 18so237430227obc.2 for ; Mon, 28 Dec 2015 09:10:09 -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=mJqZrPgS/r5TinEnXUd3wpwSI7V3aL2W/nWir55e6QU=; b=QYTPT/+ak8H0Qtl3mur6qyTYpmE9yNdRXjxBVnkLNKvbhIH2chiAy60Oo1v4JRbTb/ bgHnAW4V7bn9MMWB+BEGm/1GeYvoMDEOPVL7jl1UGAal92PfMXE7f4MhcLuyvGhKFvBc tFBBD5ykLCX3gPSTqTqk8cW7G+1K3hgzxlCKY= 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=mJqZrPgS/r5TinEnXUd3wpwSI7V3aL2W/nWir55e6QU=; b=ABEWzZoYohY8dhtKtW3VcL/45meZxESqiLEe+zWkQ7GnSnnRxCVFGcIASrPYhK+15I fEIQ7eDHat/hald/h8hZUYsD7TfEgR8+3GF86EGVq7hD9ZXG8wktuIMmRSiFtSkBAtsg I1yQvIVnTf5LU4UYZZ+2LX1GbpuoDM+F5YQO0TeDp0WJGKCr9GflqV6QLbznZe5vUWZz 6SNxxITabM1Dy/xvmtTFQYmQXgEbxnc4oDO8dQUEdIjiC0RJCS7dthAwMlSBqRmy+qth ltLBqxR3z8Gcr5TgP5BnD+c4/4GP7L8kU92MUyGOuMbCHfKpzf3zus76cEjgpeT/luiN zKtg== X-Gm-Message-State: ALoCoQmxL010h2YW8i7FqZUBQtS5tEwxB/RTrkSmp8ddLZqUbEiXZht6CcL6nbRtbDGKPIYxO4ojUmd7+RVsW8SNdCuAaN6JMw== X-Received: by 10.60.132.199 with SMTP id ow7mr32806443oeb.67.1451322608918; Mon, 28 Dec 2015 09:10:08 -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 k6sm19400651oia.18.2015.12.28.09.10.08 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Mon, 28 Dec 2015 09:10:08 -0800 (PST) From: Bill Fischofer To: lng-odp@lists.linaro.org Date: Mon, 28 Dec 2015 11:10:02 -0600 Message-Id: <1451322603-21299-1-git-send-email-bill.fischofer@linaro.org> X-Mailer: git-send-email 2.5.0 X-Topics: patch Subject: [lng-odp] [API-NEXT PATCHv3 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 | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/include/odp/api/schedule.h b/include/odp/api/schedule.h index 55191f9..68ba594 100644 --- a/include/odp/api/schedule.h +++ b/include/odp/api/schedule.h @@ -88,27 +88,35 @@ 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_NO_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. * * @param from Output parameter for the source queue (where the event was * dequeued from). Ignored if NULL.