github.com/pingcap/ticdc@v0.0.0-20220526033649-485a10ef2652/pkg/workerpool/pool.go (about)

     1  // Copyright 2020 PingCAP, Inc.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // See the License for the specific language governing permissions and
    12  // limitations under the License.
    13  
    14  package workerpool
    15  
    16  import (
    17  	"context"
    18  	"time"
    19  )
    20  
    21  // WorkerPool runs a number of Goroutines that process the submitted events.
    22  // Each EventHandle is bound to a fixed worker thread to prevent data races.
    23  type WorkerPool interface {
    24  	// RegisterEvent returns a handle that can be used to trigger the execution of `f`.
    25  	// `f` will be called with a context that is a child of the context with which Run is called.
    26  	// TODO more reasonable usage of contexts, potentially involving context merging.
    27  	RegisterEvent(f func(ctx context.Context, event interface{}) error) EventHandle
    28  
    29  	// Run runs the WorkerPool.
    30  	// Internally several Goroutines are spawned.
    31  	Run(ctx context.Context) error
    32  }
    33  
    34  // EventHandle is a handle for a registered event.
    35  // Since events are executed asynchronously, errors should be collected from ErrCh().
    36  // EventHandles SHOULD NOT be assumed to be thread safe.
    37  type EventHandle interface {
    38  	// AddEvent adds an `event` object to the internal queue, so that the `f` used to register the handle can be called.
    39  	// Note: events are always processed in the order they are added.
    40  	// Unregistering the EventHandle MAY CAUSE EVENT LOSSES. But for an event lost, any event after it is guaranteed to be lost too.
    41  	// Cancelling `ctx` here will cancel the on-going or next execution of the event.
    42  	AddEvent(ctx context.Context, event interface{}) error
    43  
    44  	// SetTimer is used to provide a function that is periodic called, as long as the EventHandle has not been unregistered.
    45  	// The current implementation uses as the base clock source a ticker whose interval is the const workerPoolDefaultClockSourceInterval.
    46  	// DO NOT set an interval less than workerPoolDefaultClockSourceInterval.
    47  	// Cancelling `ctx` here will cancel the on-going or next execution of `f`.
    48  	SetTimer(ctx context.Context, interval time.Duration, f func(ctx context.Context) error) EventHandle
    49  
    50  	// Unregister removes the EventHandle from the WorkerPool.
    51  	// Note: Unregister WILL block until the operation has taken effect, i.e. the handler will not be executed after
    52  	// Unregister returns. Unregister WILL NOT attempt to wait for pending events to complete, which means the last few events can be lost.
    53  	Unregister()
    54  
    55  	// ErrCh returns a channel that outputs the first non-nil result of events submitted to this EventHandle.
    56  	// Note that a non-nil result of an event cancels the EventHandle, so there is at most one error.
    57  	ErrCh() <-chan error
    58  
    59  	// OnExit is used to provide a function that will be called when the handle exits abnormally.
    60  	OnExit(f func(err error)) EventHandle
    61  }