1  package actor
  2  
  3  import (
  4  	"context"
  5  	"fmt"
  6  
  7  	"github.com/lightningnetwork/lnd/fn/v2"
  8  )
  9  
 10  // ErrActorTerminated indicates that an operation failed because the target
 11  // actor was terminated or in the process of shutting down.
 12  var ErrActorTerminated = fmt.Errorf("actor terminated")
 13  
 14  // ErrEmptyActorID is returned when an actor is created with an empty ID.
 15  var ErrEmptyActorID = fmt.Errorf("actor ID must not be empty")
 16  
 17  // ErrNilBehavior is returned when an actor is created with a nil behavior.
 18  var ErrNilBehavior = fmt.Errorf("actor behavior must not be nil")
 19  
 20  // ErrDuplicateActorID is returned when attempting to register an actor with an
 21  // ID that is already in use within the actor system.
 22  var ErrDuplicateActorID = fmt.Errorf("actor ID already registered")
 23  
 24  // BaseMessage is a helper struct that can be embedded in message types defined
 25  // outside the actor package to satisfy the Message interface's unexported
 26  // messageMarker method.
 27  type BaseMessage struct{}
 28  
 29  // messageMarker implements the unexported method for the Message interface,
 30  // allowing types that embed BaseMessage to satisfy the Message interface.
 31  func (BaseMessage) messageMarker() {}
 32  
 33  // Message is a sealed interface for actor messages. Actors will receive
 34  // messages conforming to this interface. The interface is "sealed" by the
 35  // unexported messageMarker method, meaning only types that can satisfy it
 36  // (e.g., by embedding BaseMessage or being in the same package) can be
 37  // Messages.
 38  type Message interface {
 39  	// messageMarker is a private method that makes this a sealed interface
 40  	// (see BaseMessage for embedding).
 41  	messageMarker()
 42  
 43  	// MessageType returns the type name of the message for
 44  	// routing/filtering.
 45  	MessageType() string
 46  }
 47  
 48  // Future represents the result of an asynchronous computation. It allows
 49  // consumers to wait for the result (Await), apply transformations upon
 50  // completion (ThenApply), or register a callback to be executed when the
 51  // result is available (OnComplete).
 52  type Future[T any] interface {
 53  	// Await blocks until the result is available or the context is
 54  	// cancelled, then returns it.
 55  	Await(ctx context.Context) fn.Result[T]
 56  
 57  	// ThenApply registers a function to transform the result of a future.
 58  	// The original future is not modified, a new instance of the future is
 59  	// returned. If the passed context is cancelled while waiting for the
 60  	// original future to complete, the new future will complete with the
 61  	// context's error.
 62  	ThenApply(ctx context.Context, fn func(T) T) Future[T]
 63  
 64  	// OnComplete registers a function to be called when the result of the
 65  	// future is ready. If the passed context is cancelled before the future
 66  	// completes, the callback function will be invoked with the context's
 67  	// error.
 68  	OnComplete(ctx context.Context, fn func(fn.Result[T]))
 69  }
 70  
 71  // Promise is an interface that allows for the completion of an associated
 72  // Future. It provides a way to set the result of an asynchronous operation.
 73  // The producer of an asynchronous result uses a Promise to set the outcome,
 74  // while consumers use the associated Future to retrieve it.
 75  type Promise[T any] interface {
 76  	// Future returns the Future interface associated with this Promise.
 77  	// Consumers can use this to Await the result or register callbacks.
 78  	Future() Future[T]
 79  
 80  	// Complete attempts to set the result of the future. It returns true if
 81  	// this call successfully set the result (i.e., it was the first to
 82  	// complete it), and false if the future had already been completed.
 83  	Complete(result fn.Result[T]) bool
 84  }
 85  
 86  // TellOnlyRef is a reference to an actor that only supports "tell" operations.
 87  // This is useful for scenarios where only fire-and-forget message passing is
 88  // needed, or to restrict capabilities.
 89  type TellOnlyRef[M Message] interface {
 90  	// Tell sends a message without waiting for a response. If the
 91  	// context is cancelled before the message can be sent to the actor's
 92  	// mailbox, the message may be dropped.
 93  	Tell(ctx context.Context, msg M)
 94  
 95  	// ID returns the unique identifier for this actor.
 96  	ID() string
 97  }
 98  
 99  // ActorRef is a reference to an actor that supports both "tell" and "ask"
100  // operations. It embeds TellOnlyRef and adds the Ask method for
101  // request-response interactions.
102  type ActorRef[M Message, R any] interface {
103  	TellOnlyRef[M]
104  
105  	// Ask sends a message and returns a Future for the response.
106  	// The Future will be completed with the actor's reply or an error
107  	// if the operation fails (e.g., context cancellation before send).
108  	Ask(ctx context.Context, msg M) Future[R]
109  }
110  
111  // ActorBehavior defines the logic for how an actor processes incoming messages.
112  // It is a strategy interface that encapsulates the actor's reaction to
113  // messages.
114  type ActorBehavior[M Message, R any] interface {
115  	// Receive processes a message and returns a Result. The provided
116  	// context is the actor's internal context, which can be used to
117  	// detect actor shutdown requests.
118  	Receive(actorCtx context.Context, msg M) fn.Result[R]
119  }