libc-eventmachine 0.12.5.42

data/docs/README

@@ -0,0 +1,74 @@
+$Id$
+
+= RUBY/EventMachine
+
+Homepage::  http://rubyeventmachine.com
+Copyright:: (C) 2006-07 by Francis Cianfrocca. All Rights Reserved.
+Email:: gmail address: garbagecat10
+
+EventMachine is copyrighted free software made available under the terms
+of either the GPL or Ruby's License. See the file COPYING for full licensing
+information.
+See EventMachine and EventMachine::Connection for documentation and
+usage examples.
+
+EventMachine implements a fast, single-threaded engine for arbitrary network
+communications. It's extremely easy to use in Ruby. EventMachine wraps all
+interactions with IP sockets, allowing programs to concentrate on the
+implementation of network protocols. It can be used to create both network
+servers and clients. To create a server or client, a Ruby program only needs
+to specify the IP address and port, and provide a Module that implements the
+communications protocol. Implementations of several standard network protocols
+are provided with the package, primarily to serve as examples. The real goal
+of EventMachine is to enable programs to easily interface with other programs
+using TCP/IP, especially if custom protocols are required.
+
+A Ruby program uses EventMachine by registering the addresses and ports of
+network servers and clients, and then entering an event-handling loop.
+EventMachine contains glue code in Ruby which will execute callbacks to
+user-supplied code for all significant events occurring in the clients
+and servers. These events include connection acceptance, startup, data-receipt,
+shutdown, and timer events. Arbitrary processing can be performed by user code
+during event callbacks, including sending data to one or more remote network
+peers, startup and shutdown of network connections, and installation of new
+event handlers.
+
+The EventMachine implements a very familiar model for network programming.
+It emphasizes: 1) the maximum possible isolation of user code from network
+objects like sockets; 2) maximum performance and scalability; and 3) extreme
+ease-of-use for user code. It attempts to provide a higher-level interface
+than similar projects which expose a variety of low-level event-handling
+and networking objects to Ruby programs.
+
+The design and implementation of EventMachine grows out of nearly ten years
+of experience writing high-performance, high-scaling network server applications.
+We have taken particular account of the challenges and lessons described as
+the "C10K problem" by Dan Kegel and others.
+
+EventMachine consists of an extension library written in C++ (which can be
+accessed from languages other than Ruby), and a Ruby module which can be dropped
+into user programs. On most platforms, EventMachine uses the
+<tt>select(2)</tt> system call,
+so it will run on a large range of Unix-like systems and on Microsoft
+Windows with good performance and scalability. On Linux 2.6 kernels, EventMachine
+automatically configures itself to use <tt>epoll(4)</tt> instead of
+<tt>select(2),</tt> so scalability on that platform can be significantly
+improved.
+
+Here's a fully-functional echo server written with EventMachine:
+
+      require 'rubygems'
+      require 'eventmachine'
+
+      module EchoServer
+        def receive_data data
+          send_data ">>>you sent: #{data}"
+          close_connection if data =~ /quit/i
+        end
+      end
+
+      EventMachine::run {
+        EventMachine::start_server "192.168.0.100", 8081, EchoServer
+      }
+
+

data/docs/RELEASE_NOTES

@@ -0,0 +1,96 @@
+$Id$
+
+RUBY/EventMachine RELEASE NOTES
+
+--------------------------------------------------
+Version: 0.9.0, released xxXXX07
+Added Erlang-like distributed-computing features
+
+--------------------------------------------------
+Version: 0.8.0, released 23Jun07
+Added an epoll implementation for Linux 2.6 kernels.
+Added evented #popen.
+
+--------------------------------------------------
+Version: 0.7.3, released 22May07
+Added a large variety of small features. See the ChangeLog.
+
+--------------------------------------------------
+Version: 0.7.1, released xxNov06
+Added protocol handlers for line-oriented protocols.
+Various bug fixes.
+
+--------------------------------------------------
+Version: 0.7.0, released 20Nov06
+Added a fix in em.cpp/ConnectToServer to fix a fatal exception that
+occurred in FreeBSD when connecting successfully to a remote server.
+
+--------------------------------------------------
+Version: 0.6.0, released xxJul06
+Added deferred operations, suggested by Don Stocks, amillionhitpoints@yahoo.com.
+
+--------------------------------------------------
+Version: 0.5.4, released xxJun06
+Added get_peername support for streams and datagrams.
+
+--------------------------------------------------
+Version: 0.5.3, released 17May06
+Fixed bugs in extconf.rb, thanks to Daniel Harple, dharple@generalconsumption.org.
+Added proper setup.rb and rake tasks, thanks to Austin Ziegler.
+Fixed a handful of reported problems with builds on various platforms.
+
+--------------------------------------------------
+Version: 0.5.2, released 05May06
+Made several nonvisible improvements to the Windows
+implementation.
+Added an exception-handling patch contributed by Jeff Rose, jeff@rosejn.net.
+Added a dir-config patch contributed anonymously.
+Supported builds on Solaris.
+
+--------------------------------------------------
+Version: 0.5.1, released 05May06
+Made it possible to pass a Class rather than a Module
+to a protocol handler.
+Added Windows port.
+
+--------------------------------------------------
+Version: 0.5.0, released 30Apr06
+Added a preliminary SSL/TLS extension. This will probably
+change over the next few releases.
+
+--------------------------------------------------
+Version: 0.4.5, released 29Apr06
+Changed ext files so the ruby.h is installed after unistd.h
+otherwise it doesn't compile on gcc 4.1
+
+--------------------------------------------------
+Version: 0.4.2, released 19Apr06
+Changed the Ruby-glue so the extension will play nicer
+in the sandbox with Ruby threads.
+Added an EventMachine::run_without_threads API to
+switch off the thread-awareness for better performance
+in programs that do not spin any Ruby threads.
+
+--------------------------------------------------
+Version: 0.4.1, released 15Apr06
+Reworked the shared-object interface to make it easier to
+use EventMachine from languages other than Ruby.
+
+--------------------------------------------------
+Version: 0.3.2, released 12Apr06
+Added support for a user-supplied block in EventMachine#connect.
+
+--------------------------------------------------
+Version: 0.3.1, released 11Apr06
+Fixed bug that prevented EventMachine from being run multiple
+times in a single process.
+
+--------------------------------------------------
+Version: 0.3.0, released 10Apr06
+Added method EventHandler::Connection::post_init
+
+--------------------------------------------------
+Version: 0.2.0, released 10Apr06
+Added method EventHandler::stop
+
+

data/docs/SMTP

@@ -0,0 +1,9 @@
+$Id$
+
+
+[DOCUMENT UNDER CONSTRUCTION]
+
+This note details the usage of EventMachine's built-in support for SMTP. EM supports both client and server connections, which will be described in separate sections.
+
+
+

data/docs/SPAWNED_PROCESSES

@@ -0,0 +1,93 @@
+$Id$
+
+[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.
+
+
+=== What are Spawned Processes?
+
+Spawned Processes in EventMachine are inspired directly by the "processes" found in the Erlang programming language. EM deliberately borrows much (but not all) of Erlang's terminology. However, EM's spawned processes differ from Erlang's in ways that reflect not only Ruby style, but also the fact that Ruby is not a functional language like Erlang.
+
+Let's proceed with a complete, working code sample that we will analyze line by line. Here's an EM implementation of the "ping-pong" program that also appears in the Erlang tutorial:
+
+
+ require 'eventmachine'
+ 
+ EM.run {
+   pong = EM.spawn {|x, ping|
+     puts "Pong received #{x}"
+     ping.notify( x-1 )
+   }
+ 
+   ping = EM.spawn {|x|
+     if x > 0
+       puts "Pinging #{x}"
+       pong.notify x, self
+     else
+       EM.stop
+     end
+   }
+ 
+   ping.notify 3
+ }
+
+If you run this program, you'll see the following output:
+
+ Pinging 3
+ Pong received 3
+ Pinging 2
+ Pong received 2
+ Pinging 1
+ Pong received 1
+
+Let's take it step by step.
+
+EventMachine#spawn works very much like the built-in function spawn in Erlang. It returns a reference to a Ruby object of class EventMachine::SpawnedProcess, which is actually a schedulable entity. In Erlang, the value returned from spawn is called a "process identifier" or "pid." But we'll refer to the Ruby object returned from EM#spawn simply as a "spawned process."
+
+You pass a Ruby block with zero or more parameters to EventMachine#spawn. Like all Ruby blocks, this one is a closure, so it can refer to variables defined in the local context when you call EM#spawn.
+
+However, the code block passed to EM#spawn does NOT execute immediately by default. Rather, it will execute only when the Spawned Object is "notified." In Erlang, this process is called "message passing," and is done with the operator !, but in Ruby it's done simply by calling the #notify method of a spawned-process object. The parameters you pass to #notify must match those defined in the block that was originally passed to EM#spawn.
+
+When you call the #notify method of a spawned-process object, EM's reactor core will execute the code block originally passed to EM#spawn, at some point in the future. (#notify itself merely adds a notification to the object's message queue and ALWAYS returns immediately.)
+
+When a SpawnedProcess object executes a notification, it does so in the context of the SpawnedProcess object itself. The notified code block can see local context from the point at which EM#spawn was called. However, the value of "self" inside the notified code block is a reference to the SpawnedProcesss object itself.
+
+An EM spawned process is nothing more than a Ruby object with a message queue attached to it. You can have any number of spawned processes in your program without compromising scalability. You can notify a spawned process any number of times, and each notification will cause a "message" to be placed in the queue of the spawned process. Spawned processes with non-empty message queues are scheduled for execution automatically by the EM reactor. Spawned processes with no visible references are garbage-collected like any other Ruby object.
+
+Back to our code sample:
+
+   pong = EM.spawn {|x, ping|
+     puts "Pong received #{x}"
+     ping.notify( x-1 )
+   }
+
+This simply creates a spawned process and assigns it to the local variable pong. You can see that the spawned code block takes a numeric parameter and a reference to another spawned process. When pong is notified, it expects to receive arguments corresponding to these two parameters. It simply prints out the number it receives as the first argument. Then it notifies the spawned process referenced by the second argument, passing it the first argument minus 1.
+
+And then the block ends, which is crucial because otherwise nothing else can run. (Remember that in LC, scheduled entities run to completion and are never preempted.)
+
+On to the next bit of the code sample:
+
+   ping = EM.spawn {|x|
+     if x > 0
+       puts "Pinging #{x}"
+       pong.notify x, self
+     else
+       EM.stop
+     end
+   }
+
+Here, we're spawning a process that takes a single (numeric) parameter. If the parameter is greater than zero, the block writes it to the console. It then notifies the spawned process referenced by the pong local variable, passing as arguments its number argument, and a reference to itself. The latter reference, as you saw above, is used by pong to send a return notification.
+
+If the ping process receives a zero value, it will stop the reactor loop and end the program.
+
+Now we've created a pair of spawned processes, but nothing else has happened. If we stop now, the program will spin in the EM reactor loop, doing nothing at all. Our spawned processes will never be scheduled for execution.
+
+But look at the next line in the code sample:
+
+   ping.notify 3
+
+This line gets the ping-pong ball rolling. We call ping's #notify method, passing the argument 3. This causes a message to be sent to the ping spawned process. The message contains the single argument, and it causes the EM reactor to schedule the ping process. And this in turn results in the execution of the Ruby code block passed to EM#spawn when ping was created. Everything else proceeds as a result of the messages that are subsequently passed to each other by the spawned processes.
+
+[TODO, present the outbound network i/o use case, and clarify that spawned processes are interleaved with normal i/o operations and don't interfere with them at all. Also, blame Erlang for the confusing term "process"]
+

data/docs/TODO

@@ -0,0 +1,10 @@
+$Id$
+
+TODO List:
+
+12Aug06: Noticed by Don Stocks. A TCP connect-request that results
+in a failed DNS resolution fires a fatal error back to user code.
+Uuuuuugly. We should probably cause an unbind event to get fired
+instead, and add some parameterization so the caller can detect
+the nature of the failure.
+

data/ext/binder.cpp

@@ -0,0 +1,126 @@
+/*****************************************************************************
+
+$Id$
+
+File:     binder.cpp
+Date:     07Apr06
+
+Copyright (C) 2006-07 by Francis Cianfrocca. All Rights Reserved.
+Gmail: blackhedd
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of either: 1) the GNU General Public License
+as published by the Free Software Foundation; either version 2 of the
+License, or (at your option) any later version; or 2) Ruby's License.
+
+See the file COPYING for complete licensing information.
+
+*****************************************************************************/
+
+#include "project.h"
+
+#define DEV_URANDOM "/dev/urandom"
+
+
+map<string, Bindable_t*> Bindable_t::BindingBag;
+
+
+/********************************
+STATIC Bindable_t::CreateBinding
+********************************/
+
+string Bindable_t::CreateBinding()
+{
+	static int index = 0;
+	static string seed;
+
+	if ((index >= 1000000) || (seed.length() == 0)) {
+		#ifdef OS_UNIX
+		int fd = open (DEV_URANDOM, O_RDONLY);
+		if (fd < 0)
+			throw std::runtime_error ("No entropy device");
+
+		unsigned char u[16];
+		size_t r = read (fd, u, sizeof(u));
+		if (r < sizeof(u))
+			throw std::runtime_error ("Unable to read entropy device");
+
+		unsigned char *u1 = (unsigned char*)u;
+		char u2 [sizeof(u) * 2 + 1];
+
+		for (size_t i=0; i < sizeof(u); i++)
+			sprintf (u2 + (i * 2), "%02x", u1[i]);
+
+		seed = string (u2);
+		#endif
+
+
+		#ifdef OS_WIN32
+		UUID uuid;
+		UuidCreate (&uuid);
+		unsigned char *uuidstring = NULL;
+		UuidToString (&uuid, &uuidstring);
+		if (!uuidstring)
+			throw std::runtime_error ("Unable to read uuid");
+		seed = string ((const char*)uuidstring);
+
+		RpcStringFree (&uuidstring);
+		#endif
+
+		index = 0;
+
+
+	}
+
+	stringstream ss;
+	ss << seed << (++index);
+	return ss.str();
+}
+
+
+/*****************************
+STATIC: Bindable_t::GetObject
+*****************************/
+
+Bindable_t *Bindable_t::GetObject (const char *binding)
+{
+  string s (binding ? binding : "");
+  return GetObject (s);
+}
+
+/*****************************
+STATIC: Bindable_t::GetObject
+*****************************/
+
+Bindable_t *Bindable_t::GetObject (const string &binding)
+{
+  map<string, Bindable_t*>::const_iterator i = BindingBag.find (binding);
+  if (i != BindingBag.end())
+    return i->second;
+  else
+    return NULL;
+}
+
+
+/**********************
+Bindable_t::Bindable_t
+**********************/
+
+Bindable_t::Bindable_t()
+{
+	Binding = Bindable_t::CreateBinding();
+	BindingBag [Binding] = this;
+}
+
+
+
+/***********************
+Bindable_t::~Bindable_t
+***********************/
+
+Bindable_t::~Bindable_t()
+{
+	BindingBag.erase (Binding);
+}
+
+

data/ext/binder.h

@@ -0,0 +1,48 @@
+/*****************************************************************************
+
+$Id$
+
+File:     binder.h
+Date:     07Apr06
+
+Copyright (C) 2006-07 by Francis Cianfrocca. All Rights Reserved.
+Gmail: blackhedd
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of either: 1) the GNU General Public License
+as published by the Free Software Foundation; either version 2 of the
+License, or (at your option) any later version; or 2) Ruby's License.
+
+See the file COPYING for complete licensing information.
+
+*****************************************************************************/
+
+#ifndef __ObjectBindings__H_
+#define __ObjectBindings__H_
+
+
+class Bindable_t
+{
+	public:
+		static string CreateBinding();
+		static Bindable_t *GetObject (const string&);
+		static Bindable_t *GetObject (const char*);
+		static map<string, Bindable_t*> BindingBag;
+
+	public:
+		Bindable_t();
+		virtual ~Bindable_t();
+
+		const string &GetBinding() {return Binding;}
+		const char *GetBindingChars() {return Binding.c_str();}
+
+	private:
+		string Binding;
+};
+
+
+
+
+
+#endif // __ObjectBindings__H_
+