feat: westworldwithmessaging. add entitymanager, telegram, messagehandlers, delayedmessages, expand baseentity

chapter-2-state-driven-agent-design/westworldwithmessaging/telegram.go

@@ -0,0 +1,68 @@
+package westworldwithmessaging
+
+import "math"
+
+// Telegram is the Go version of the C++ struct:
+//
+//	struct Telegram
+//	{
+//	    int Sender;
+//	    int Receiver;
+//	    int Msg;
+//	    double DispatchTime;
+//	    void* ExtraInfo;
+//	};
+//
+// It's one message passed between entities through the dispatcher /
+// entity manager we'll build next: who sent it, who it's for, what
+// it says, when it should actually go out, and any extra data riding
+// along with it. The book's "/* CONSTRUCTORS OMITTED */" means we
+// haven't been shown how one gets built yet, so this is just the
+// plain data shape for now, no constructor.
+type Telegram struct {
+	// Sender is the ID of the entity that sent this telegram.
+	Sender int
+
+	// Receiver is the ID of the entity meant to receive this telegram.
+	Receiver int
+
+	// Msg is the message itself. The book keeps this as a plain int
+	// rather than the MessageType enum, presumably so the dispatcher
+	// can stay generic and doesn't need to know about every possible
+	// message type - we're matching that choice exactly rather than
+	// tightening it to MessageType ourselves.
+	Msg int
+
+	// DispatchTime supports delayed messages: instead of going out
+	// immediately, a telegram can be stamped with the time it should
+	// actually be delivered. C++'s "double" becomes Go's float64 -
+	// Go has no bare "double" keyword, float64 is its 64-bit
+	// floating-point type.
+	DispatchTime float64
+
+	// ExtraInfo carries any additional data that should travel with
+	// the message. C++'s "void*" (a pointer with no fixed type -
+	// "could point to anything") becomes Go's "any" (an alias for
+	// interface{} - "could hold a value of any type"). Whoever reads
+	// ExtraInfo later type-asserts it back to something concrete.
+	ExtraInfo any
+}
+
+// smallestDelay is our stand-in for the book's "a quarter of a
+// second" tolerance - it doesn't give us an exact named constant for
+// this, just that written description.
+const smallestDelay = 0.25
+
+// telegramsMatch is our own Go version of the behavior the book
+// describes for Telegram.h's overloaded == operator (we haven't been
+// shown that file's actual code, only this description): two
+// telegrams count as the same message if they're headed the same
+// direction with the same content, and their dispatch times are less
+// than smallestDelay apart. This is what keeps a burst of near-
+// identical messages from flooding an entity's queue.
+func telegramsMatch(a, b Telegram) bool {
+	return a.Sender == b.Sender &&
+		a.Receiver == b.Receiver &&
+		a.Msg == b.Msg &&
+		math.Abs(a.DispatchTime-b.DispatchTime) < smallestDelay
+}