From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id C2BF5A0561; Mon, 20 Apr 2020 15:47:21 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id C556A1D5E7; Mon, 20 Apr 2020 15:47:20 +0200 (CEST) Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [205.139.110.120]) by dpdk.org (Postfix) with ESMTP id 34E4F1D14B for ; Mon, 20 Apr 2020 15:47:19 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1587390438; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=b7BKrPTjO3BRx/blwrO+IOl0CAACcaBpRMK1EdF2wiA=; b=Z/EN/QmYsTZGEfJxoxxNOyovV5vGnN4K4L3bI8Sg6TdKu/4Lw89W0PLyw0bbfwEheV5ihH H3SI2WDF1573nEzr8DEtplc13Q0p3HnouedHPu7OH0OS3pYiO5TnKqLwCdZzlwyFMPKU1k INV/sXJZ/OE/aca8WTQpf0uFnnTMtTA= Received: from mail-ua1-f70.google.com (mail-ua1-f70.google.com [209.85.222.70]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-466--ZzdpkWsNcK0bNhFXtW-KA-1; Mon, 20 Apr 2020 09:47:16 -0400 X-MC-Unique: -ZzdpkWsNcK0bNhFXtW-KA-1 Received: by mail-ua1-f70.google.com with SMTP id v17so4824618uao.7 for ; Mon, 20 Apr 2020 06:47:16 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=Rj+2UEwvhvA4qFBvaP0qyodlwSL5lnnYxZtaPzcddA8=; b=aHNxvPlmzTo1La7KsfvO91iJb9+5fTqjXQbbTi2uUoVNGgv7x279KVVP8Uztjy5WR5 dCRAmTkrqsXLTg4e5hq0YZ8DYiaymyTcOvna/L4l6vO590ia4+bdCKzDiRf9/urtjFi3 ku/QSNiMk7Mn9j7LnMfUP2qCGbJu+gmWzqc2XRPSJzvQlvUBhmVbEslMpON6VTXxvck+ VtubFk5HDsO/X/A1JhIjGsGGr/Gwl5GwNbwX6097tt6CNtXI19fF+qmKj4Z/O4QdimQm +NZdJDHbxmXQD5U8A3I7sJlEmBoGNLiay5e2DhIyt3owl0tv12Se/BsCqvz81FWJN0eI 5X0g== X-Gm-Message-State: AGi0Puak3ADeMY85WnQS9OfcpajygSMZRhUi7Lhl8arArVk04exqHXJ9 7yITsB+rA9Zos9F6iuDT0etAJ7HChD2E0hAMTEmN6sFu3iZlfc5mkpm/5DcW3/+WdfCpTt5K4bM k/M0bW759tsvvTMyPJX4= X-Received: by 2002:a9f:2204:: with SMTP id 4mr7505506uad.87.1587390435757; Mon, 20 Apr 2020 06:47:15 -0700 (PDT) X-Google-Smtp-Source: APiQypLa2hD0tS3nZMsAEGKV9sn6V9OFAN5zNDtlOx3oFmDVIiLEURv1bzOH141qE2dbEItfMKQY5/CTGu/7W3TBNA4= X-Received: by 2002:a9f:2204:: with SMTP id 4mr7505464uad.87.1587390435290; Mon, 20 Apr 2020 06:47:15 -0700 (PDT) MIME-Version: 1.0 References: <20200418163225.17635-1-konstantin.ananyev@intel.com> <20200420121113.9327-1-konstantin.ananyev@intel.com> <20200420121113.9327-11-konstantin.ananyev@intel.com> In-Reply-To: <20200420121113.9327-11-konstantin.ananyev@intel.com> From: David Marchand Date: Mon, 20 Apr 2020 15:47:03 +0200 Message-ID: To: Konstantin Ananyev , Honnappa Nagarahalli Cc: dev , jielong.zjl@antfin.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Subject: Re: [dpdk-dev] [PATCH v6 10/10] doc: update ring guide X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" On Mon, Apr 20, 2020 at 2:12 PM Konstantin Ananyev wrote: > > Changed the rte_ring chapter in programmer's guide to reflect > the addition of new sync modes and peek style API. I'd like to split this as follows, see below. I have a couple of typos too. If you are fine with it, I'll proceed and squash when merging. > > Signed-off-by: Konstantin Ananyev > --- > doc/guides/prog_guide/ring_lib.rst | 95 ++++++++++++++++++++++++++++++ > 1 file changed, 95 insertions(+) > > diff --git a/doc/guides/prog_guide/ring_lib.rst b/doc/guides/prog_guide/r= ing_lib.rst > index 8cb2b2dd4..668e67ecb 100644 > --- a/doc/guides/prog_guide/ring_lib.rst > +++ b/doc/guides/prog_guide/ring_lib.rst > @@ -349,6 +349,101 @@ even if only the first term of subtraction has over= flowed: > uint32_t entries =3D (prod_tail - cons_head); > uint32_t free_entries =3D (mask + cons_tail -prod_head); > >From here, this first part would go to patch2 "ring: prepare ring to allow new sync schemes". > +Producer/consumer synchronization modes > +--------------------------------------- > + > +rte_ring supports different synchronization modes for porducer and consu= mers. producers* > +These modes can be specified at ring creation/init time via ``flags`` pa= rameter. > +That should help user to configure ring in way most suitable for his double space to remove. users? > +specific usage scenarios. > +Currently supported modes: > + > +MP/MC (default one) > +~~~~~~~~~~~~~~~~~~~ > + > +Multi-producer (/multi-consumer) mode. This is a default enqueue (/deque= ue) > +mode for the ring. In this mode multiple threads can enqueue (/dequeue) > +objects to (/from) the ring. For 'classic' DPDK deployments (with one th= read > +per core) this is usually most suitable and fastest synchronization mode= . the most* > +As a well known limitaion - it can perform quite pure on some overcommit= ted limitation* > +scenarios. > + > +SP/SC > +~~~~~ > +Single-producer (/single-consumer) mode. In this mode only one thread at= a time > +is allowed to enqueue (/dequeue) objects to (/from) the ring. End of first part. Then the second part that would go to patch3 "ring: introduce RTS ring mode= ". > + > +MP_RTS/MC_RTS > +~~~~~~~~~~~~~ > + > +Multi-producer (/multi-consumer) with Relaxed Tail Sync (RTS) mode. > +The main difference from original MP/MC algorithm is that from the original* > +tail value is increased not by every thread that finished enqueue/dequeu= e, > +but only by the last one. > +That allows threads to avoid spinning on ring tail value, > +leaving actual tail value change to the last thread at a given instance. > +That technique helps to avoid Lock-Waiter-Preemtion (LWP) problem on tai= l the Lock-Waiter-Preemption* > +update and improves average enqueue/dequeue times on overcommitted syste= ms. > +To achieve that RTS requires 2 64-bit CAS for each enqueue(/dequeue) ope= ration: > +one for head update, second for tail update. > +In comparison original MP/MC algorithm requires one 32-bit CAS the original* > +for head update and waiting/spinning on tail value. > + End of second part. Third part that would go to patch 5 "ring: introduce HTS ring mode". > +MP_HTS/MC_HTS > +~~~~~~~~~~~~~ > + > +Multi-producer (/multi-consumer) with Head/Tail Sync (HTS) mode. > +In that mode enqueue/dequeue operation is fully serialized: > +at any given moment only one enqueue/dequeue operation can proceed. > +This is achieved by allowing a thread to proceed with changing ``head.va= lue`` > +only when ``head.value =3D=3D tail.value``. > +Both head and tail values are updated atomically (as one 64-bit value). > +To achieve that 64-bit CAS is used by head update routine. > +That technique also avoids Lock-Waiter-Preemtion (LWP) problem on tail the Lock-Waiter-Preemption* > +update and helps to improve ring enqueue/dequeue behavior in overcommitt= ed > +scenarios. Another advantage of fully serialized producer/consumer - > +it provides ability to implement MT safe peek API for rte_ring. it provides the ability* End of 3rd part. Last part would go to patch 7 "ring: introduce peek style API". > + > + > +Ring Peek API > +------------- > + > +For ring with serialized producer/consumer (HTS sync mode) it is possib= le double space. > +to split public enqueue/dequeue API into two phases: > + > +* enqueue/dequeue start > + > +* enqueue/dequeue finish > + > +That allows user to inspect objects in the ring without removing them > +from it (aka MT safe peek) and reserve space for the objects in the ring > +before actual enqueue. > +Note that this API is available only for two sync modes: > + > +* Single Producer/Single Consumer (SP/SC) > + > +* Multi-producer/Multi-consumer with Head/Tail Sync (HTS) > + > +It is a user responsibility to create/init ring with appropriate sync mo= des > +selected. As an example of usage: > + > +.. code-block:: c > + > + /* read 1 elem from the ring: */ > + uint32_t n =3D rte_ring_dequeue_bulk_start(ring, &obj, 1, NULL); > + if (n !=3D 0) { > + /* examine object */ > + if (object_examine(obj) =3D=3D KEEP) > + /* decided to keep it in the ring. */ > + rte_ring_dequeue_finish(ring, 0); > + else > + /* decided to remove it from the ring. */ > + rte_ring_dequeue_finish(ring, n); > + } > + > +Note that between ``_start_`` and ``_finish_`` none other thread can pro= ceed > +with enqueue(/dequeue) operation till ``_finish_`` completes. > + --=20 David Marchand