////////////////////////////////////////////////////////////// // // DrivenEngine // // This module embodies the idea of an "event-driven game engine." We want the // engine to be event-driven because an event-driven engine is a deterministic // state machine. That, in turn, makes it possible to do replay logging. // // The DrivenEngine module provides two APIs: the 'engine-side' API, and the // 'driver-side' API. // // The engine-side API looks like a typical collection of I/O primitives. It // includes methods to open sockets, read and write sockets, read lua source, // get the clock, and so forth. // // But in reality, these I/O functions don't ever call operating system // functions like "read" or "write" or "connect." They don't call the operating // system at all - not even indirectly, through a wrapper. Therefore, they // can't really do any I/O. When you use one of these I/O functions to (say) // write some data to a communication channel, the only thing that happens is // that the data is put into a buffer. The actual transmission of the data // happens elsewhere, in what is called the "Driver." Likewise, when you use // one of these I/O functions to read data, it only returns data that was // previously stored by the "Driver." // // The "Driver" is a module that implements the actual I/O. It is highly // OS-dependent code, because it contains code to manipulate sockets, time // clocks, and the like. // // From the perspective of the driver, the DrivenEngine is a C++ object that // acts like a state machine. This state machine is driven forward by I/O // events. The DrivenEngine provides an API where the driver can feed in these // I/O events. // // Notice that the usual call graph is inverted: in most application programs, // the application calls the operating system to do I/O. But when using class // DrivenEngine, it's the other way around: the driver calls into class // DrivenEngine to drive it forward. I/O routines drive computation. // // So the upshot of all this is that the DrivenEngine is a deterministic state // machine, free of all OS-specific code. // ////////////////////////////////////////////////////////////// // // Here are the rules for what the driver must do: // // * Before doing anything else, the driver must select one of the three // logmodes. // // * If 'logmode_replay' is selected, then the driver must proceed to invoke // 'drv_step_logfile' over and over until it returns false. In replay mode, // the driver should not do anything else. // // * If 'logmode_write' or 'logmode_none' is selected, the driver must proceed // to drive the application. Follow the remainder of these steps. // // * Open a hardwired list of ports for listening. // // * Repeat the following steps over and over: // // - If the engine asked that the lua source be refreshed, read the source // from disk and call 'drv_set_lua_source'. // // - Get a list of recently-closed channels using drv_get_closed_channels. // Close any socket associated with these channels and free all resources. // // - Get a list of recently-opened channels using drv_get_opened_channels. // Open new outgoing connections for these channels. // // - Do an OS 'poll'. The poll should include the sockets for all channels // in the channel list, all listening ports, and stdio. // // - If the poll indicates that a listening port has acceptable // connections, accept and call drv_notify_accept. Associate the // accepted socket with the channel. // // - If the poll indicates that a connection can accept outgoing data, use // drv_peek_outgoing to fetch some data to write, and write it. Use // drv_sent_outgoing_bytes to indicate that the data was sent. // // - If the poll indicates that a connection has incoming data, read the // data then push it into the channel using drv_recv_incoming. // // - If the poll indicates that STDIO can be read/written, use // drv_peek_outgoing, drv_sent_outgoing, and drv_recv_incoming in the // same manner as you would for a socket. // // - Use 'drv_invoke_event_update' to invoke the engine's update callback. // ////////////////////////////////////////////////////////////// #ifndef DRIVENENGINE_HPP #define DRIVENENGINE_HPP #include #include #include #include #include "streambuffer.hpp" #include "util.hpp" class DrivenEngine; class Channel { public: // Get the buffers associated with this channel. // StreamBuffer *out() { return sb_out_.get(); } StreamBuffer *in() { return sb_in_.get(); } // The channel ID. These are reused. // int chid() { return chid_; } // If this is a socket connection, the receiver's port number. // int port() { return port_; } // If this is an outgoing socket connection, get the target host. const std::string &target() { return target_; } // True if the remote closed the connection, or a failure occurred. // bool closed() const { return closed_; } // Get the channel's error message. // // If this is an empty string, there is no error. If this is set, // then the channel is also closed. // std::string error() const { return error_; } // True if the channel is in readline mode. // // Stdio always starts with this enabled, other channels always start // with this disabled. // bool readline_enabled() const { return readline_enabled_; } // Put the channel into readline mode. // // Caution: the channel better be coming from a raw tty, otherwise, // this is going to produce weird results. // void set_readline(bool enabled); // You may delete any channel except for stdio. This closes // the channel. // ~Channel(); private: // Constructor is deliberately private. Use // DrivenEngine::new_outgoing_channel to create outgoing socket channels. // Channel(DrivenEngine *de, int chid, int port, const std::string &target); int readline_space() { return READLINE_MAX - readline_len_; } int echo_space() { return READLINE_MAX - echo_len_; } void feed_readline(int nbytes, const char *bytes); private: static const int READLINE_MAX=512; DrivenEngine *driven_; int chid_; std::unique_ptr sb_in_; std::unique_ptr sb_out_; int port_; bool closed_; std::string error_; std::string target_; char readline_buf_[READLINE_MAX]; int readline_len_; char readline_lastc_; char echo_buf_[READLINE_MAX]; int echo_len_; bool readline_enabled_; friend class DrivenEngine; }; using UniqueChannel = std::unique_ptr; class DrivenEngine { public: ////////////////////////////////////////////////////////////// // // The following methods are the 'engine' side of the pipe. // ////////////////////////////////////////////////////////////// // The update callback. You may override this in a subclass. // This will be called whenever anything changes. // virtual void event_init(int argc, char *argv[]) {} virtual void event_update() {} // Specify the set of listening ports. // This can only be used during the init routine. // void listen_port(int port); // Get the current time. // // DRIVER: This returns the time most recently stored by the driver // using drv_set_clock. // double get_clock(); // Create a channel and open an outgoing connection. // // DRIVER: The channel object is created instantly, but it does nothing // until the driver notices the new channel. The driver is responsible for // actually opening the connection and relaying data into the channel using // drv_get_target, drv_peek_outgoing, drv_sent_outgoing, drv_recv_incoming. // UniqueChannel new_outgoing_channel(const std::string &target); // Create a new channel from any pending incoming connection. If there is no // incoming connection, returns nullptr. // // DRIVER: The driver must be hardwired to know what ports to listen on. // When the driver notices a new incoming connection, it calls // drv_notify_accept, which triggers the creation of the channel. The // channel is put into the incoming channel queue, which is fetched by this // method. The driver is responsible for relaying data into the channel // using drv_get_target, drv_peek_outgoing, drv_sent_outgoing, // drv_recv_incoming. // UniqueChannel new_incoming_channel(); // Obtain the stdio channel. There is only one stdio channel. It is owned // by the DrivenEngine. It is an error to delete the stdio channel. // // DRIVER: the stdio channel is created automatically when the DrivenEngine // is created. The driver is responsible for relaying data into the channel // using drv_get_target, drv_peek_outgoing, drv_sent_outgoing, // drv_recv_incoming. // Channel *get_stdio_channel(); // Fetches the lua source, and takes ownership of it. The DrivenEngine // no longer contains the source after calling this. // util::LuaSourcePtr get_lua_source(); // Rescan the lua source directory. The lua source directory is read once, // automatically, at engine creation time. If you want to read it again, // you must trigger a rescan. The rescan is not instantaneous. // // DRIVER: this merely sets a flag, which the driver will notice later, // causing the driver to update the lua source. // void rescan_lua_source(); // Stop the driver. The engine should call this when it's done // and there's nothing left to do. // void stop_driver(); ////////////////////////////////////////////////////////////// // // The following methods are the 'driver' side of the pipe. // ////////////////////////////////////////////////////////////// // The maximum channel ID plus one. // static const int MAX_CHAN = 256; // Get a list of all the listening ports. The driver is expected // to fetch this set shortly after the event_init callback is invoked. // void drv_get_listen_ports(std::set &ports); // Get a list of all recently-closed channels. The driver should // discard all socket information associated with these channels. // Caution: this may contain channels that the driver has never // heard of. In that case, just ignore the close-request. // void drv_get_new_closed(std::set &opened); // Get a list of all recently-opened channels that were created using // drv_new_outgoing_channel. The driver should initiate outgoing // connections for these channels. // void drv_get_new_outgoing(std::set &closed); // Get the target of a channel. A target is a string like // "www.whatever.com:80". It indicates the host and port that the channel // is supposed to be talking to. Non-socket channels and incoming channels // have empty targets. // const std::string &drv_get_target(int chid); // Return true if the outgoing buffer is empty. // bool drv_outgoing_empty(int chid); // Get a pointer to the bytes in the outgoing buffer. The pointer returned // here is naturally only valid until the buffer is changed. This function // is used for all channels, including sockets and stdio. // void drv_peek_outgoing(int chid, int *nbytes, const char **bytes); // Notifies the channel that some bytes were transmitted. This causes those // bytes to be removed from the outgoing buffer. This function is used for // all channels, including sockets and stdio. // void drv_sent_outgoing(int chid, int nbytes); // Notifies the channel that some bytes were received. This causes those // bytes to be appended to the incoming buffer. This function is used for // all channels, including sockets and stdio. // void drv_recv_incoming(int chid, int nbytes, const char *bytes); // Notify the channel that the connection was closed. This includes all // sorts of closes, including friendly termination, all the way to network // failure. Closing the channel doesn't delete it. The engine is // responsible for noticing that the channel closed and the engine must // delete it. Closing a channel prevents it from showing up in // 'drv_list_channels'. // void drv_notify_close(int chid, const std::string &err); // Notify the DrivenEngine that somebody connected to an incoming port. // This will cause the DrivenEngine to allocate a new channel and put the // new channel into the incoming channels queue. Returns the new channel // ID. The new incoming channel appears in the 'drv_list_channels' list, // even before the engine pops the channel from the incoming channels queue. // int drv_notify_accept(int port); // Set the clock. The driver is expected to periodically check the system // clock and feed the value into the engine. // void drv_set_clock(double t); // Set the lua source code. The driver is expected to read the lua source // code and store it (using this function) once before invoking // void drv_set_lua_source(util::LuaSourcePtr source); // Invoke the init or update event. // void drv_invoke_event_init(int argc, char *argv[]); void drv_invoke_event_update(); // Check the 'rescan_lua_source' flag. If this flag is set, it means // that the engine wants the driver to rescan the lua source code. // When the driver sees this flag, it should rescan the source and call // drv_set_source. // bool drv_get_rescan_lua_source(); // If true, the engine is done. Stop the driver. // bool drv_get_stop_driver(); ////////////////////////////////////////////////////////////// // // Creation and Destruction. // ////////////////////////////////////////////////////////////// // Constructor. // // Most initialization is achieved by 'drv_xxx' functions, so // this constructor takes no arguments. // DrivenEngine(); // Destructor. // // It is necessary to delete all channels before deleting the // DrivenEngine. The destructor will verify that this has been done. // virtual ~DrivenEngine(); // Set/Get Global Pointer. // // Normally, there is a single global "DrivenEngine" instance. // We provide a global pointer to store this instance. This is // a raw pointer, you must manually delete the DrivenEngine. // static void set(DrivenEngine *de); static DrivenEngine *get(); private: // Find a currently-unused channel ID. Channel IDs // are small integers that are reused. int find_unused_chid(); // Get the channel associated with the specified channel ID. Channel *get_chid(int chid); private: Channel *channels_[MAX_CHAN]; int next_unused_chid_; UniqueChannel stdio_channel_; std::vector accepted_channels_; std::set new_closed_; std::set new_outgoing_; util::LuaSourcePtr lua_source_; std::set listen_ports_; bool rescan_lua_source_; double clock_; bool stop_driver_; friend class Channel; }; using UniqueDrivenEngine = std::unique_ptr; using DrivenEngineMaker = UniqueDrivenEngine (*)(); #endif // DRIVENENGINE_HPP