模块 wjybxx.commons.disruptor
程序包 cn.wjybxx.disruptor

类 MultiProducerSequencer

java.lang.Object
cn.wjybxx.disruptor.RingBufferSequencer
cn.wjybxx.disruptor.MultiProducerSequencer
所有已实现的接口:
ProducerBarrier, SequenceBarrier, Sequencer
public class MultiProducerSequencer extends RingBufferSequencer
多生产者模型下的序号生成器

注意: 使用该序号生成器时，在调用WaitStrategy.waitFor(long, ProducerBarrier, ConsumerBarrier) 后必须调用ProducerBarrier.getHighestPublishedSequence(long, long) 确定真正可用的序号。因为多生产者模型下，生产者之间是无锁的，预分配序号，那么真正填充的数据可能是非连续的。

建议阅读我多年前注释的disruptor源码 Disruptor源码注释

作者:
wjybxx date - 2024/1/17

  • 字段详细资料

    • gatingSequenceCache

      protected final Sequence gatingSequenceCache
      网关序列的最小序号缓存。 小心：多线程更新的情况下，有可能小于真实的gatingSequence -- 结果是良性的。

      由于消费者的Sequence变更较为频繁，因此消费者的Sequence的缓存极易失效。 如果生产者频繁读取消费者的Sequence，极易遇见缓存失效问题（伪共享），从而影响性能。 通过缓存一个值（在必要的时候更新），可以极大的减少对消费者的Sequence的读操作，从而提高性能。 PS: 使用一个变化频率较低的值代替一个变化频率较高的值，提高读效率。

  • 构造器详细资料

    • MultiProducerSequencer

      public MultiProducerSequencer(int bufferSize, long sleepNanos, WaitStrategy waitStrategy, @Nullable SequenceBlocker blocker)

  • 方法详细资料

    • claim

      public void claim(long sequence)
      从接口复制的说明: SequenceBarrier
      设置当前屏障的序号。 1. 仅在初始化屏障时使用。 2. 这是个很危险的方法，避免在运行中使用，否则可能导致错误。 3. 屏障的初始值为SequenceBarrier.INITIAL_SEQUENCE。
      指定者:
      claim 在接口中 SequenceBarrier
      覆盖:
      claim 在类中 RingBufferSequencer
      参数:
      sequence - 要初始化的值

    • setPublished

      protected final void setPublished(long sequence)

    • setPublished

      protected final void setPublished(long lo, long hi)

    • publish

      public void publish(long sequence)
      从接口复制的说明: ProducerBarrier
      发布指定序号的数据，表示sequence对应的数据可用 Publishes a sequence. Call when the event has been filled.
      参数:
      sequence - the sequence to be published.

    • publish

      public void publish(long lo, long hi)
      从接口复制的说明: ProducerBarrier
      批量发布数据，表示 [lowest,highest]区间段整段数据可用。 一般情况下，hi是ProducerBarrier.next()等方法申请到的最大序号，但也可能不是，生产者可能分段发布数据，以避免阻塞消费者。

      Batch publish sequences. Called when all of the events have been filled.

      参数:
      lo - first sequence number to publish
      hi - last sequence number to publish

    • isPublished

      public boolean isPublished(long sequence)
      从接口复制的说明: ProducerBarrier
      指定序号的数据是否已发布。 注意： 1. 该测试只测试序号自身，不测试其前置序号。 2. 通常情况下你不应该使用它，唯一合理的情况是：清理RingBuffer的时候。

      Confirms if a sequence is published and the event is available for use; non-blocking.

      参数:
      sequence - of the buffer to check
      返回:
      true if the sequence is available for use, false if not

    • getHighestPublishedSequence

      public long getHighestPublishedSequence(long lowerBound, long availableSequence)
      从接口复制的说明: ProducerBarrier
      查询 [nextSequence , availableSequence] 区间段之间连续发布的最大序号。 该接口用于消费者屏障查询真实可用的序号。

      由于多线程的生产者是先申请序号，再发布数据；因此SequenceBarrier.sequence()指向的是即将发布数据的槽，而不一定已经具备数据。 而消费者只能顺序消费，因此【只要消费者的依赖可能包含生产者】，在观察到依赖的最大可用序号后，都应该查询真实可用的序号。

      Get the highest sequence number that can be safely read from the ring buffer. Depending on the implementation of the Sequencer this call may need to scan a number of values in the Sequencer. The scan will range from nextSequence to availableSequence. If there are no available values >= nextSequence the return value will be nextSequence - 1. To work correctly a consumer should pass a value that is 1 higher than the last sequence that was successfully processed.

      参数:
      lowerBound - The sequence to start scanning from.
      availableSequence - The sequence to scan to.
      返回:
      The highest value that can be safely read, will be at least nextSequence - 1.

    • remainingCapacity

      public long remainingCapacity()
      从类复制的说明: RingBufferSequencer
      当前剩余容量。 并不一定具有价值，因为多线程模型下查询容器的当前大小，它反映的总是一个旧值。

      Get the remaining capacity for this sequencer.

      指定者:
      remainingCapacity 在类中 RingBufferSequencer
      返回:
      The number of slots remaining.

    • hasAvailableCapacity

      public boolean hasAvailableCapacity(int requiredCapacity)
      从接口复制的说明: ProducerBarrier
      是否有足够的空间 Has the buffer got capacity to allocate another sequence. This is a concurrent method so the response should only be taken as an indication of available capacity.
      参数:
      requiredCapacity - in the buffer
      返回:
      true if the buffer has the capacity to allocate the next sequence otherwise false.

    • next

      public long next()
      从接口复制的说明: ProducerBarrier
      获取下一个事件的序号，空间不足时会阻塞(等待)。 申请完空间之后,必须使用 ProducerBarrier.publish(long) 发布，否则会导致整个数据结构不可用。

      Claim the next event in sequence for publishing.

      返回:
      the claimed sequence value

    • next

      public long next(int n)
      从接口复制的说明: ProducerBarrier
      获取接下来的n个事件的序号，空间不足时会阻塞(等待)。 申请完空间之后，必须使用 ProducerBarrier.publish(long, long) 发布，否则会导致整个数据结构不可用

      Claim the next n events in sequence for publishing. This is for batch event producing. Using batch producing requires a little care and some math. 

       int n = 10;
 long hi = sequencer.next(n);
 long lo = hi - (n - 1);
 for (long sequence = lo; sequence <= hi; sequence++) {
     // Do work.
 }
 sequencer.publish(lo, hi);
      参数:
      n - the number of sequences to claim
      返回:
      the highest claimed sequence value

    • nextInterruptibly

      public long nextInterruptibly() throws InterruptedException
      从接口复制的说明: ProducerBarrier
      在ProducerBarrier.next()基础上会响应中断请求
      抛出:
      InterruptedException - 如果申请期间线程被中断

    • nextInterruptibly

      public long nextInterruptibly(int n) throws InterruptedException
      从接口复制的说明: ProducerBarrier
      在ProducerBarrier.next(int)基础上会响应中断请求
      抛出:
      InterruptedException - 如果申请期间线程被中断

    • tryNext

      public long tryNext()
      从接口复制的说明: ProducerBarrier
      尝试获取下一个事件的序列，空间不足时抛出异常。 申请完空间之后,必须使用 ProducerBarrier.publish(long) 发布，否则会导致整个数据结构不可用。

      Attempt to claim the next event in sequence for publishing. Will return the number of the slot if there is at least requiredCapacity slots available.

      返回:
      申请成功则返回对应的序号，否则返回 -1

    • tryNext

      public long tryNext(int n)
      从接口复制的说明: ProducerBarrier
      尝试获取接下来n个数据的最后一个数据索引位置。不会阻塞,空间不足时抛出异常。 申请完空间之后，必须使用 ProducerBarrier.publish(long, long) 发布，否则会导致整个数据结构不可用 使用该方法可以避免死锁

      Attempt to claim the next n events in sequence for publishing. Will return the highest numbered slot if there is at least requiredCapacity slots available. Have a look at ProducerBarrier.next() for a description on how to use this method.

      参数:
      n - 需要申请的序号数量
      返回:
      申请成功则返回对应的序号，否则返回 -1