github.com/lirm/aeron-go@v0.0.0-20230415210743-920325491dc4/cluster/cluster.go (about)

     1  package cluster
     2  
     3  import (
     4  	"github.com/lirm/aeron-go/aeron/atomic"
     5  	"github.com/lirm/aeron-go/aeron/idlestrategy"
     6  	"github.com/lirm/aeron-go/cluster/codecs"
     7  )
     8  
     9  type Cluster interface {
    10  
    11  	// LogPosition returns the position the log has reached in bytes as of the current message
    12  	LogPosition() int64
    13  
    14  	// MemberId returns the unique id for the hosting member of the cluster. Useful only for debugging purposes
    15  	MemberId() int32
    16  
    17  	// Role returns the role the cluster node is playing
    18  	Role() Role
    19  
    20  	// Time returns the cluster time as time units since 1 Jan 1970 UTC
    21  	Time() int64
    22  
    23  	// TimeUnit returns the unit of time applied when timestamping and time operations
    24  	TimeUnit() codecs.ClusterTimeUnitEnum
    25  
    26  	// IdleStrategy returns the IdleStrategy which should be used by the service when it experiences back-pressure on egress,
    27  	// closing sessions, making timer requests, or any long-running actions
    28  	IdleStrategy() idlestrategy.Idler
    29  
    30  	// ScheduleTimer schedules a timer for a given deadline and provide a correlation id to identify the timer when it expires or
    31  	// for cancellation. This action is asynchronous and will race with the timer expiring.
    32  	//
    33  	// If the correlationId is for an existing scheduled timer then it will be rescheduled to the new deadline. However,
    34  	// it is best to generate correllationIds in a monotonic fashion and be aware of potential clashes with other
    35  	// services in the same cluster. Service isolation can be achieved by using the upper bits for service id.
    36  	//
    37  	// Timers should only be scheduled or cancelled in the context of processing
    38  	// - onSessionMessage
    39  	// - onTimerEvent
    40  	// - onSessionOpen
    41  	// - onSessionClose
    42  	// If applied to other events then they are not guaranteed to be reliable.
    43  	//
    44  	// Callers of this method should loop until the method succeeds.
    45  	//
    46  	// The cluster's idle strategy must be used in the body of the loop to allow for the clustered service to be
    47  	// shutdown if required.
    48  	//
    49  	// ScheduleTimer returns true if the event to schedule a timer request has been sent or false if back-pressure is applied
    50  	ScheduleTimer(correlationId int64, deadline int64) bool
    51  
    52  	// CancelTimer cancels a previously scheduled timer. This action is asynchronous and will race with the timer expiring.
    53  	//
    54  	// Timers should only be scheduled or cancelled in the context of processing
    55  	// - onSessionMessage
    56  	// - onTimerEvent
    57  	// - onSessionOpen
    58  	// - onSessionClose
    59  	// If applied to other events then they are not guaranteed to be reliable.
    60  	//
    61  	// Callers of this method should loop until the method succeeds.
    62  	//
    63  	// CancelTimer   returns true if the event to cancel request has been sent or false if back-pressure is applied.
    64  	CancelTimer(correlationId int64) bool
    65  
    66  	// Offer a message as ingress to the cluster for sequencing. This will happen efficiently over IPC to the
    67  	// consensus module and set the cluster session as the negative value of the cluster's ServiceID
    68  	//
    69  	// Callers of this method should loop until the method succeeds.
    70  	//
    71  	// The cluster's idle strategy must be used in the body of the loop to allow for the clustered service to be
    72  	// shutdown if required
    73  	Offer(*atomic.Buffer, int32, int32) int64
    74  }