github.com/asynkron/protoactor-go@v0.0.0-20240308120642-ef91a6abee75/actor/doc.go (about)

     1  /*
     2  Package actor declares the types used to represent actors in the Actor Model.
     3  
     4  The actors model provide a high level abstraction for writing concurrent and distributed systems. This approach
     5  simplifies the burden imposed on engineers, such as explicit locks and concurrent access to shared state, as actors
     6  receive messages synchronously.
     7  
     8  The following quote from Wikipedia distills the definition of an actor down to its essence
     9  
    10  	In response to a message that it receives, an actor can: make local decisions, create more actors,
    11  	send more messages, and determine how to respond to the next message received.
    12  
    13  # Creating Actors
    14  
    15  Props provide the building blocks for declaring how actors should be created. The following example defines an actor
    16  using a function literal to process messages:
    17  
    18  	var props Props = actor.PropsFromFunc(func(c Context) {
    19  		// process messages
    20  	})
    21  
    22  Alternatively, a type which conforms to the Actor interface, by defining a single Receive method, can be used.
    23  
    24  	type MyActor struct {}
    25  
    26  	func (a *MyActor) Receive(c Context) {
    27  		// process messages
    28  	}
    29  
    30  	var props Props = actor.PropsFromProducer(func() Actor { return &MyActor{} })
    31  
    32  Spawn and SpawnNamed use the given props to create a running instances of an actor. Once spawned, the actor is
    33  ready to process incoming messages. To spawn an actor with a unique name, use
    34  
    35  	pid := context.Spawn(props)
    36  
    37  The result of calling Spawn is a unique PID or process identifier.
    38  
    39  Each time an actor is spawned, a new mailbox is created and associated with the PID. Messages are sent to the mailbox
    40  and then forwarded to the actor to process.
    41  
    42  # Processing Messages
    43  
    44  An actor processes messages via its Receive handler. The signature of this function is:
    45  
    46  	Receive(c actor.Context)
    47  
    48  The actor system guarantees that this method is called synchronously, therefore there is no requirement to protect
    49  shared state inside calls to this function.
    50  
    51  # Communicating With Actors
    52  
    53  A PID is the primary interface for sending messages to actors. Context.Send is used to send an asynchronous
    54  message to the actor associated with the PID:
    55  
    56  	context.Send(pid, "Hello World")
    57  
    58  Depending on the requirements, communication between actors can take place synchronously or asynchronously. Regardless
    59  of the circumstances, actors always communicate via a PID.
    60  
    61  When sending a message using PID.Request or PID.RequestFuture, the actor which receives the message will respond
    62  using the Context.Sender method, which returns the PID of the sender.
    63  
    64  For synchronous communication, an actor will use a Future and wait for the result before continuing. To send a message
    65  to an actor and wait for a response, use the RequestFuture method, which returns a Future:
    66  
    67  	f := actor.RequestFuture(pid,"Hello", 50 * time.Millisecond)
    68  	res, err := f.Result() // waits for pid to reply
    69  */
    70  package actor