eventmachine 0.9.0 → 0.10.0

data/DEFERRABLES

@@ -1,8 +1,8 @@
-$Id: DEFERRABLES 541 2007-09-17 15:08:36Z blackhedd $
+$Id: DEFERRABLES 551 2007-09-22 12:57:36Z blackhedd $
 
 [DOCUMENT UNDER CONSTRUCTION]
 
-EventMachine (EM) adds two different formalisms for lightweight concurrency to the Ruby programmer's toolbox: spawned processes and deferrables. This note will show you how to use spawned processes. For more information, see the separate document LIGHTWEIGHT_CONCURRENCY.
+EventMachine (EM) adds two different formalisms for lightweight concurrency to the Ruby programmer's toolbox: spawned processes and deferrables. This note will show you how to use deferrables. For more information, see the separate document LIGHTWEIGHT_CONCURRENCY.
 
 
 === What are Deferrables?
@@ -132,7 +132,7 @@ Now of course it's somewhat trivial to define two callbacks in the same method,
 
 Remember that you can add a callback or an errback to a Deferrable at any point in time, regardless of whether the status of the deferred operation is known (more precisely, regardless of when #set_deferred_status is called on the object). Even hours or days later.
 
-When you add a callback or errback to a Deferrable object on which #set_deferred_status has not yet been called, the callback/errback is queued up for future execution, inside the Deferrable object. When you add a callback or errback to a Deferrable on which #set_deferred_status has already been called, the callback/errback will be executed immediately. Your code doesn't have to worry about the ordering, and there are no timing issues, as you would expect with a threaded approach.
+When you add a callback or errback to a Deferrable object on which #set_deferred_status has not yet been called, the callback/errback is queued up for future execution, inside the Deferrable object. When you add a callback or errback to a Deferrable on which #set_deferred_status has already been called, the callback/errback will be executed immediately. Your code doesn't have to worry about the ordering, and there are no timing issues, as there would be with a threaded approach.
 
 For more information on Deferrables and their typical usage patterns, look in the EM unit tests. There are also quite a few sugarings (including EM::Deferrable#future) that make typical Deferrable usages syntactically easier to work with.
 

data/PURE_RUBY

@@ -0,0 +1,77 @@
+$Id: PURE_RUBY 602 2007-12-05 18:45:29Z blackhedd $
+
+EventMachine is supplied in three alternative versions.
+
+1) A version that includes a Ruby extension written in C++. This version requires compilation;
+2) A version for JRuby that contains a precompiled JAR file written in Java;
+3) A pure Ruby version that has no external dependencies and can run in any Ruby environment.
+
+The Java version of EventMachine is packaged in a distinct manner and must be installed using a
+special procedure. This version is described fully in a different document, and not considered
+further here.
+
+The C++ and pure-Ruby versions, however, are shipped in the same distribution. You use the same
+files (either tarball or Ruby gem) to install both of these versions.
+
+If you intend to use the C++ version, you must successfully compile EventMachine after you install it.
+(The gem installation attempts to perform this step automatically.)
+
+If you choose not to compile the EventMachine C++ extension, or if your compilation fails for any
+reason, you still have a fully-functional installation of the pure-Ruby version of EM.
+
+However, for technical reasons, a default EM installation (whether or not the compilation succeeds)
+will always assume that the compiled ("extension") implementation should be used.
+
+If you want your EM program to use the pure Ruby version, you must specifically request it. There
+are two ways to do this: by setting either a Ruby global variable, or an environment string.
+
+The following code will invoke the pure-Ruby implementation of EM:
+
+ $eventmachine_library = :pure_ruby
+ require 'eventmachine'
+
+ EM.library_type #=> "pure_ruby"
+
+Notice that this requires a code change and is not the preferred way to select pure Ruby, unless
+for some reason you are absolutely sure you will never want the compiled implementation.
+
+Setting the following environment string has the same effect:
+
+ export EVENTMACHINE_LIBRARY="pure_ruby"
+
+This technique gives you the flexibility to select either version at runtime with no code changes.
+
+Support
+
+The EventMachine development team has committed to support precisely the same APIs for all the
+various implementations of EM.
+
+This means that you can expect any EM program to behave identically, whether you use pure Ruby,
+the compiled C++ extension, or JRuby. Deviations from this behavior are to be considered bugs
+and should be reported as such.
+
+There is a small number of exceptions to this rule, which arise from underlying platform
+distinctions. Notably, EM#epoll is a silent no-op in the pure Ruby implementation.
+
+
+When Should You Use the Pure-Ruby Implementation of EM?
+
+
+Use the pure Ruby implementation of EM when you must support a platform for which no C++ compiler
+is available, or on which the standard EM C++ code can't be compiled.
+
+Keep in mind that you don't need a C++ compiler in order to deploy EM applications that rely on
+the compiled version, so long as appropriate C++ runtime libraries are available on the target platform.
+
+In extreme cases, you may find that you can develop software with the compiled EM version, but are
+not allowed to install required runtime libraries on the deployment system(s). This would be another
+case in which the pure Ruby implementation can be useful.
+
+In general you should avoid the pure Ruby version of EM when performance and scalability are important.
+EM in pure Ruby will necessarily run slower than the compiled version. Depending on your application
+this may or may not be a key issue.
+
+Also, since EPOLL is not supported in pure Ruby, your applications will be affected by Ruby's built-in
+limit of 1024 file and socket descriptors that may be open in a single process. For maximum scalability
+and performance, always use EPOLL if possible.
+

data/ext/cmain.cpp

@@ -1,6 +1,6 @@
 /*****************************************************************************
 
-$Id: cmain.cpp 502 2007-08-24 09:29:53Z blackhedd $
+$Id: cmain.cpp 585 2007-11-27 14:29:34Z blackhedd $
 
 File:     cmain.cpp
 Date:     06Apr06
@@ -181,6 +181,17 @@ extern "C" void evma_close_connection (const char *binding, int after_writing)
 	ConnectionDescriptor::CloseConnection (binding, (after_writing ? true : false));
 }
 
+/***********************************
+evma_report_connection_error_status
+***********************************/
+
+extern "C" int evma_report_connection_error_status (const char *binding)
+{
+	if (!EventMachine)
+		throw std::runtime_error ("not initialized");
+	return ConnectionDescriptor::ReportErrorStatus (binding);
+}
+
 /********************
 evma_stop_tcp_server
 ********************/
@@ -264,6 +275,22 @@ extern "C" int evma_get_subprocess_pid (const char *binding, pid_t *pid)
 		return 0;
 }
 
+/**************************
+evma_get_subprocess_status
+**************************/
+
+extern "C" int evma_get_subprocess_status (const char *binding, int *status)
+{
+	if (!EventMachine)
+		throw std::runtime_error ("not initialized");
+	if (status) {
+		*status = EventMachine->SubprocessExitStatus;
+		return 1;
+	}
+	else
+		return 0;
+}
+
 
 /*********************
 evma_signal_loopbreak
@@ -331,7 +358,19 @@ extern "C" void evma_set_timer_quantum (int interval)
 {
 	if (!EventMachine)
 		throw std::runtime_error ("not initialized");
-  EventMachine->SetTimerQuantum (interval);
+	EventMachine->SetTimerQuantum (interval);
+}
+
+/************************
+evma_set_max_timer_count
+************************/
+
+extern "C" void evma_set_max_timer_count (int ct)
+{
+	// This may only be called if the reactor is not running.
+	if (EventMachine)
+		throw std::runtime_error ("already initialized");
+	EventMachine_t::SetMaxTimerCount (ct);
 }
 
 /******************

data/ext/ed.cpp

@@ -1,6 +1,6 @@
 /*****************************************************************************
 
-$Id: ed.cpp 497 2007-08-15 13:57:49Z blackhedd $
+$Id: ed.cpp 572 2007-11-15 23:13:45Z blackhedd $
 
 File:     ed.cpp
 Date:     06Apr06
@@ -243,6 +243,21 @@ void ConnectionDescriptor::CloseConnection (const char *binding, bool after_writ
 		ed->ScheduleClose (after_writing);
 }
 
+/***********************************************
+STATIC: ConnectionDescriptor::ReportErrorStatus
+***********************************************/
+
+int ConnectionDescriptor::ReportErrorStatus (const char *binding)
+{
+	// TODO: This is something of a hack, or at least it's a static method of the wrong class.
+	// TODO: Poor polymorphism here. We should be calling one virtual method
+	// instead of hacking out the runtime information of the target object.
+	ConnectionDescriptor *cd = dynamic_cast <ConnectionDescriptor*> (Bindable_t::GetObject (binding));
+	if (cd)
+		return cd->_ReportErrorStatus();
+	return -1;
+}
+
 
 
 /**************************************
@@ -395,7 +410,7 @@ void ConnectionDescriptor::Read()
 	LastIo = gCurrentLoopTime;
 
 	int total_bytes_read = 0;
-	char readbuffer [16 * 1024];
+	char readbuffer [16 * 1024 + 1];
 
 	for (int i=0; i < 10; i++) {
 		// Don't read just one buffer and then move on. This is faster
@@ -612,6 +627,27 @@ void ConnectionDescriptor::_WriteOutboundData()
 }
 
 
+/****************************************
+ConnectionDescriptor::_ReportErrorStatus
+****************************************/
+
+int ConnectionDescriptor::_ReportErrorStatus()
+{
+	int error;
+	socklen_t len;
+	len = sizeof(error);
+	#ifdef OS_UNIX
+	int o = getsockopt (GetSocket(), SOL_SOCKET, SO_ERROR, &error, &len);
+	#endif
+	#ifdef OS_WIN32
+	int o = getsockopt (GetSocket(), SOL_SOCKET, SO_ERROR, (char*)&error, &len);
+	#endif
+	if ((o == 0) && (error == 0))
+		return 0;
+	else
+		return 1;
+}
+
 
 /******************************
 ConnectionDescriptor::StartTls
@@ -926,6 +962,27 @@ DatagramDescriptor::DatagramDescriptor (int sd, EventMachine_t *parent_em):
 {
 	memset (&ReturnAddress, 0, sizeof(ReturnAddress));
 
+	/* Provisionally added 19Oct07. All datagram sockets support broadcasting.
+	 * Until now, sending to a broadcast address would give EACCES (permission denied)
+	 * on systems like Linux and BSD that require the SO_BROADCAST socket-option in order
+	 * to accept a packet to a broadcast address. Solaris doesn't require it. I think
+	 * Windows DOES require it but I'm not sure.
+	 *
+	 * Ruby does NOT do what we're doing here. In Ruby, you have to explicitly set SO_BROADCAST
+	 * on a UDP socket in order to enable broadcasting. The reason for requiring the option
+	 * in the first place is so that applications don't send broadcast datagrams by mistake.
+	 * I imagine that could happen if a user of an application typed in an address that happened
+	 * to be a broadcast address on that particular subnet.
+	 *
+	 * This is provisional because someone may eventually come up with a good reason not to
+	 * do it for all UDP sockets. If that happens, then we'll need to add a usercode-level API
+	 * to set the socket option, just like Ruby does. AND WE'LL ALSO BREAK CODE THAT DOESN'T
+	 * EXPLICITLY SET THE OPTION.
+	 */
+
+	int oval = 1;
+	int sob = setsockopt (GetSocket(), SOL_SOCKET, SO_BROADCAST, (char*)&oval, sizeof(oval));
+
 	#ifdef HAVE_EPOLL
 	EpollEvent.events = EPOLLIN;
 	#endif
@@ -1090,7 +1147,14 @@ DatagramDescriptor::SelectForWrite
 
 bool DatagramDescriptor::SelectForWrite()
 {
-	return (GetOutboundDataSize() > 0);
+	/* Changed 15Nov07, per bug report by Mark Zvillius.
+	 * The outbound data size will be zero if there are zero-length outbound packets,
+	 * so we now select writable in case the outbound page buffer is not empty.
+	 * Note that the superclass ShouldDelete method still checks for outbound data size,
+	 * which may be wrong.
+	 */
+	//return (GetOutboundDataSize() > 0); (Original)
+	return (OutboundPages.size() > 0);
 }
 
 

data/ext/ed.h

@@ -1,6 +1,6 @@
 /*****************************************************************************
 
-$Id: ed.h 502 2007-08-24 09:29:53Z blackhedd $
+$Id: ed.h 585 2007-11-27 14:29:34Z blackhedd $
 
 File:     ed.h
 Date:     06Apr06
@@ -133,6 +133,7 @@ class ConnectionDescriptor: public EventableDescriptor
 
 		static int SendDataToConnection (const char*, const char*, int);
 		static void CloseConnection (const char*, bool);
+		static int ReportErrorStatus (const char*);
 
 		int SendOutboundData (const char*, int);
 
@@ -157,6 +158,7 @@ class ConnectionDescriptor: public EventableDescriptor
 		virtual int GetCommInactivityTimeout (int *value);
 		virtual int SetCommInactivityTimeout (int *value);
 
+
 	protected:
 		struct OutboundPage {
 			OutboundPage (const char *b, int l, int o=0): Buffer(b), Length(l), Offset(o) {}
@@ -189,6 +191,7 @@ class ConnectionDescriptor: public EventableDescriptor
 		void _DispatchInboundData (const char *buffer, int size);
 		void _DispatchCiphertext();
 		int _SendRawOutboundData (const char*, int);
+		int _ReportErrorStatus();
 
 };
 

data/ext/em.cpp

@@ -1,6 +1,6 @@
 /*****************************************************************************
 
-$Id: em.cpp 533 2007-09-14 17:36:04Z blackhedd $
+$Id: em.cpp 587 2007-12-01 13:50:32Z blackhedd $
 
 File:     em.cpp
 Date:     06Apr06
@@ -34,6 +34,33 @@ unsigned gLastTickCount;
 #endif
 
 
+/* The numer of max outstanding timers was once a const enum defined in em.h.
+ * Now we define it here so that users can change its value if necessary.
+ */
+static int MaxOutstandingTimers = 1000;
+
+
+
+/***************************************
+STATIC EventMachine_t::SetMaxTimerCount
+***************************************/
+
+void EventMachine_t::SetMaxTimerCount (int count)
+{
+	/* Allow a user to increase the maximum number of outstanding timers.
+	 * If this gets "too high" (a metric that is of course platform dependent),
+	 * bad things will happen like performance problems and possible overuse
+	 * of memory.
+	 * The actual timer mechanism is very efficient so it's hard to know what
+	 * the practical max, but 100,000 shouldn't be too problematical.
+	 */
+	if (count < 100)
+		count = 100;
+	MaxOutstandingTimers = count;
+}
+
+
+
 /******************************
 EventMachine_t::EventMachine_t
 ******************************/
@@ -1382,8 +1409,11 @@ const char *EventMachine_t::Socketpair (char * const*cmd_strings)
 		return NULL;
 	// from here, all early returns must close the pair of sockets.
 
-	// Set the socketpair nonblocking. Obviously DON'T set CLOEXEC.
-	if (!SetSocketNonblocking (sv[0]) || !SetSocketNonblocking (sv[1])) {
+	// Set the parent side of the socketpair nonblocking.
+	// We don't care about the child side, and most child processes will expect their
+	// stdout to be blocking. Thanks to Duane Johnson and Bill Kelly for pointing this out.
+	// Obviously DON'T set CLOEXEC.
+	if (!SetSocketNonblocking (sv[0])) {
 		close (sv[0]);
 		close (sv[1]);
 		return NULL;
@@ -1420,18 +1450,11 @@ EventMachine_t::OpenKeyboard
 
 const char *EventMachine_t::OpenKeyboard()
 {
-	#ifdef OS_UNIX
 	KeyboardDescriptor *kd = new KeyboardDescriptor (this);
 	if (!kd)
 		throw std::runtime_error ("no keyboard-object allocated");
 	Add (kd);
 	return kd->GetBinding().c_str();
-	#endif
-
-	#ifdef OS_WIN32
-	throw std::runtime_error ("open-keyboard is currently unavailable on this platform");
-	return NULL;
-	#endif
 }
 
 

data/ext/em.h

@@ -1,6 +1,6 @@
 /*****************************************************************************
 
-$Id: em.h 502 2007-08-24 09:29:53Z blackhedd $
+$Id: em.h 585 2007-11-27 14:29:34Z blackhedd $
 
 File:     em.h
 Date:     06Apr06
@@ -56,6 +56,9 @@ class EventMachine_t
 
 class EventMachine_t
 {
+	public:
+		static void SetMaxTimerCount (int);
+
 	public:
 		EventMachine_t (void(*event_callback)(const char*, int, const char*, int));
 		virtual ~EventMachine_t();
@@ -81,21 +84,11 @@ class EventMachine_t
 		static void SetuidString (const char*);
 		static int SetRlimitNofile (int);
 
+		int SubprocessExitStatus;
+
 		// Temporary:
 		void _UseEpoll();
 
-		/*
-	public:
-		enum { // Event names
-			TIMER_FIRED = 100,
-			CONNECTION_READ = 101,
-			CONNECTION_UNBOUND = 102,
-			CONNECTION_ACCEPTED = 103,
-			CONNECTION_COMPLETED = 104,
-			LOOPBREAK_SIGNAL = 105
-		};
-		*/
-
 
 	private:
 		bool _RunOnce();
@@ -114,7 +107,6 @@ class EventMachine_t
 
 	private:
 		enum {
-			MaxOutstandingTimers = 1000,
 			HeartbeatInterval = 2,
 			MaxEpollDescriptors = 64*1024
 		};

data/ext/eventmachine.h

@@ -1,6 +1,6 @@
 /*****************************************************************************
 
-$Id: eventmachine.h 502 2007-08-24 09:29:53Z blackhedd $
+$Id: eventmachine.h 584 2007-11-27 07:27:32Z blackhedd $
 
 File:     eventmachine.h
 Date:     15Apr06
@@ -48,6 +48,7 @@ extern "C" {
 	void evma_start_tls (const char *binding);
 	int evma_get_peername (const char *binding, struct sockaddr*);
 	int evma_get_subprocess_pid (const char *binding, pid_t*);
+	int evma_get_subprocess_status (const char *binding, int*);
 	int evma_send_data_to_connection (const char *binding, const char *data, int data_length);
 	int evma_send_datagram (const char *binding, const char *data, int data_length, const char *address, int port);
 	int evma_get_comm_inactivity_timeout (const char *binding, /*out*/int *value);
@@ -56,8 +57,10 @@ extern "C" {
 	int evma_send_file_data_to_connection (const char *binding, const char *filename);
 
 	void evma_close_connection (const char *binding, int after_writing);
+	int evma_report_connection_error_status (const char *binding);
 	void evma_signal_loopbreak();
 	void evma_set_timer_quantum (int);
+	void evma_set_max_timer_count (int);
 	void evma_setuid_string (const char *username);
 	void evma_stop_machine();