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

接口 ProducerBarrier

所有超级接口:
SequenceBarrier
所有已知实现类:
MpUnboundedBufferSequencer, MultiProducerSequencer, RingBufferSequencer, SingleProducerSequencer
public interface ProducerBarrier extends SequenceBarrier
生产者序号屏障 1. 生产者屏障负责的是生产者与生产者之间，生产者和消费者之间的协调。
2. 生产者与消费最慢的消费者之间进行协调 -- SequenceBarrier.dependentSequence()即为最慢的消费者进度，如果有消费者的话。
3. 生产者之间可能毫无关系，因此生产者之间的协调需要由屏障实现。
4. 生产者由于明确知道自己要生产的数据数量，因此tryNext(n)的接口更易于使用。

Q: 生产者为什么没有等待策略？
A：一开始我确实尝试添加等待策略，后来发现没有意义。我在SequenceBlocker中提到，生产者不能使用Condition等待消费者， 因此等待策略的扩展性很有限，除了短暂的挂起线程外，没有好的替代方法。

Q: 生产者为什么没有ConsumerBarrier.alert()信号？ A：我们将生产者归属于外部系统，而将消费者归属于内部系统。生产者可能仅有部分逻辑与Sequencer相关，我们不能使用alert信号来中断或终止生产者。

作者:
wjybxx date - 2024/1/16

  • 方法详细资料

    • hasAvailableCapacity

      boolean hasAvailableCapacity(int requiredCapacity)
      是否有足够的空间 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

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

      Claim the next event in sequence for publishing.

      返回:
      the claimed sequence value

    • next

      long next(int n)
      获取接下来的n个事件的序号，空间不足时会阻塞(等待)。 申请完空间之后，必须使用 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

    • tryNext

      long tryNext()
      尝试获取下一个事件的序列 -- 不会阻塞。 申请完空间之后,必须使用 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

      long tryNext(int n)
      尝试获取接下来n个数据的最后一个数据索引位置 -- 不会阻塞。 申请完空间之后，必须使用 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 next() for a description on how to use this method.

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

    • publish

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

    • publish

      void publish(long lo, long hi)
      批量发布数据，表示 [lowest,highest]区间段整段数据可用。 一般情况下，hi是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

      boolean isPublished(long sequence)
      指定序号的数据是否已发布。 注意： 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

      long getHighestPublishedSequence(long nextSequence, long availableSequence)
      查询 [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.

      参数:
      nextSequence - 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.

    • nextInterruptibly

      long nextInterruptibly() throws InterruptedException
      在next()基础上会响应中断请求
      抛出:
      InterruptedException - 如果申请期间线程被中断

    • nextInterruptibly

      long nextInterruptibly(int n) throws InterruptedException
      在next(int)基础上会响应中断请求
      抛出:
      InterruptedException - 如果申请期间线程被中断

    • tryNext

      long tryNext(int n, long timeout, TimeUnit unit)
      在给定时间内尝试申请序号 注意：受限于等待策略的扩展限制，该接口本质是tryNext(int)的循环快捷方法。
      参数:
      n - 需要申请的序号数量
      返回:
      申请成功则返回对应的序号，否则返回 -1

    • getBlocker

      @Nullable SequenceBlocker getBlocker()
      获取用于阻塞等待序号的阻塞器。 注意：可能为null，如果整个系统禁用了基于锁的条件等待。

    • signalAllWhenBlocking

      void signalAllWhenBlocking()
      唤醒所有因条件等待阻塞的线程 getBlocker()的快捷方法