From patchwork Mon Dec 28 14:50:55 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bill Fischofer X-Patchwork-Id: 59022 Delivered-To: patch@linaro.org Received: by 10.112.130.2 with SMTP id oa2csp1748732lbb; Mon, 28 Dec 2015 06:51:11 -0800 (PST) X-Received: by 10.140.230.134 with SMTP id a128mr74792540qhc.33.1451314271293; Mon, 28 Dec 2015 06:51:11 -0800 (PST) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id f16si30361577qhf.130.2015.12.28.06.51.10; Mon, 28 Dec 2015 06:51:11 -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 9EB43616D6; Mon, 28 Dec 2015 14:51:10 +0000 (UTC) Authentication-Results: lists.linaro.org; dkim=fail reason="verification failed; unprotected key" header.d=linaro.org header.i=@linaro.org header.b=doHM/ykZ; 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 48B75616C9; Mon, 28 Dec 2015 14:51:05 +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 91B9F616CC; Mon, 28 Dec 2015 14:51:03 +0000 (UTC) Received: from mail-oi0-f50.google.com (mail-oi0-f50.google.com [209.85.218.50]) by lists.linaro.org (Postfix) with ESMTPS id 88164616C8 for ; Mon, 28 Dec 2015 14:51:02 +0000 (UTC) Received: by mail-oi0-f50.google.com with SMTP id o124so174695331oia.1 for ; Mon, 28 Dec 2015 06:51:02 -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=WvTmsvJC3FlS2xf61+dAs0Q5E6Le7ByROwEHxQRTdXg=; b=doHM/ykZ/Hi9ZbtJqK/0QgDPitLewxnl9JYNyJxCWRvemtgA40FBKugPUokYJ2363I Jls9/m3incjozTxD3lKxbeseJz/vXFDkM+lj8H1tqR7FYOQ4X/mMw74uphIQw+28+s+U FzeoJmgodVi9VlpkMGayjJsoDYWicj2dg6u7E= 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=WvTmsvJC3FlS2xf61+dAs0Q5E6Le7ByROwEHxQRTdXg=; b=Z+gsHZW58NwpO1tdxKtAFDLkKZFpfH7ON/5jBnYt3EcpjhW5rb3ON/dg9ZQMvaT05u kzGVF76OSx1A8TpD4RvyKB9dKTJACC2gGEqJEooLtfZ/Z3j2qnz/YsIL4wPoxOTl6iri SHpPD/X+ZblpvqQqBnzDISe6zpycdY/dnmA0kzly7GuXlIFsXogTw+5AwOfpe/vXm2bw glfelwzflSzVOemU7vcFZ4LBfQFGeu0VdYuBIGWZbWJjFwvg3ySsk4uCt2ZEQaE3RVlk jeGTrH+xWjzHFoy2d9sazDN5nop2zaCm/vi5RYw7t/gY5MxC+4OeoLU1FrbikDDja6Ap I2Dw== X-Gm-Message-State: ALoCoQmUOl5h2Pcw2UxzMsyVGjFz+aZclD5ehjkRrvnYNtdsjxBiYt6n4dUzdNkQzw9zlH6K9gv0VZsTOnfNO9Y849/Up8VbyQ== X-Received: by 10.202.80.201 with SMTP id e192mr31315088oib.14.1451314262017; Mon, 28 Dec 2015 06:51:02 -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 n9sm19746507oev.17.2015.12.28.06.51.01 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Mon, 28 Dec 2015 06:51:01 -0800 (PST) From: Bill Fischofer To: lng-odp@lists.linaro.org Date: Mon, 28 Dec 2015 08:50:55 -0600 Message-Id: <1451314256-27492-1-git-send-email-bill.fischofer@linaro.org> X-Mailer: git-send-email 2.5.0 X-Topics: patch Subject: [lng-odp] [API-NEXT PATCHv2 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..749a88f 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_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.