eventmachine-win32 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/COPYING ADDED
@@ -0,0 +1,281 @@
1
+ .
2
+
3
+ GNU GENERAL PUBLIC LICENSE
4
+ Version 2, June 1991
5
+
6
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.
7
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
8
+ Everyone is permitted to copy and distribute verbatim copies
9
+ of this license document, but changing it is not allowed.
10
+
11
+ Preamble
12
+
13
+ The licenses for most software are designed to take away your
14
+ freedom to share and change it. By contrast, the GNU General Public
15
+ License is intended to guarantee your freedom to share and change free
16
+ software--to make sure the software is free for all its users. This
17
+ General Public License applies to most of the Free Software
18
+ Foundation's software and to any other program whose authors commit to
19
+ using it. (Some other Free Software Foundation software is covered by
20
+ the GNU Lesser General Public License instead.) You can apply it to
21
+ your programs, too.
22
+
23
+ When we speak of free software, we are referring to freedom, not
24
+ price. Our General Public Licenses are designed to make sure that you
25
+ have the freedom to distribute copies of free software (and charge for
26
+ this service if you wish), that you receive source code or can get it
27
+ if you want it, that you can change the software or use pieces of it
28
+ in new free programs; and that you know you can do these things.
29
+
30
+ To protect your rights, we need to make restrictions that forbid
31
+ anyone to deny you these rights or to ask you to surrender the rights.
32
+ These restrictions translate to certain responsibilities for you if you
33
+ distribute copies of the software, or if you modify it.
34
+
35
+ For example, if you distribute copies of such a program, whether
36
+ gratis or for a fee, you must give the recipients all the rights that
37
+ you have. You must make sure that they, too, receive or can get the
38
+ source code. And you must show them these terms so they know their
39
+ rights.
40
+
41
+ We protect your rights with two steps: (1) copyright the software, and
42
+ (2) offer you this license which gives you legal permission to copy,
43
+ distribute and/or modify the software.
44
+
45
+ Also, for each author's protection and ours, we want to make certain
46
+ that everyone understands that there is no warranty for this free
47
+ software. If the software is modified by someone else and passed on, we
48
+ want its recipients to know that what they have is not the original, so
49
+ that any problems introduced by others will not reflect on the original
50
+ authors' reputations.
51
+
52
+ Finally, any free program is threatened constantly by software
53
+ patents. We wish to avoid the danger that redistributors of a free
54
+ program will individually obtain patent licenses, in effect making the
55
+ program proprietary. To prevent this, we have made it clear that any
56
+ patent must be licensed for everyone's free use or not licensed at all.
57
+
58
+ The precise terms and conditions for copying, distribution and
59
+ modification follow.
60
+
61
+ GNU GENERAL PUBLIC LICENSE
62
+ TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
63
+
64
+ 0. This License applies to any program or other work which contains
65
+ a notice placed by the copyright holder saying it may be distributed
66
+ under the terms of this General Public License. The "Program", below,
67
+ refers to any such program or work, and a "work based on the Program"
68
+ means either the Program or any derivative work under copyright law:
69
+ that is to say, a work containing the Program or a portion of it,
70
+ either verbatim or with modifications and/or translated into another
71
+ language. (Hereinafter, translation is included without limitation in
72
+ the term "modification".) Each licensee is addressed as "you".
73
+
74
+ Activities other than copying, distribution and modification are not
75
+ covered by this License; they are outside its scope. The act of
76
+ running the Program is not restricted, and the output from the Program
77
+ is covered only if its contents constitute a work based on the
78
+ Program (independent of having been made by running the Program).
79
+ Whether that is true depends on what the Program does.
80
+
81
+ 1. You may copy and distribute verbatim copies of the Program's
82
+ source code as you receive it, in any medium, provided that you
83
+ conspicuously and appropriately publish on each copy an appropriate
84
+ copyright notice and disclaimer of warranty; keep intact all the
85
+ notices that refer to this License and to the absence of any warranty;
86
+ and give any other recipients of the Program a copy of this License
87
+ along with the Program.
88
+
89
+ You may charge a fee for the physical act of transferring a copy, and
90
+ you may at your option offer warranty protection in exchange for a fee.
91
+
92
+ 2. You may modify your copy or copies of the Program or any portion
93
+ of it, thus forming a work based on the Program, and copy and
94
+ distribute such modifications or work under the terms of Section 1
95
+ above, provided that you also meet all of these conditions:
96
+
97
+ a) You must cause the modified files to carry prominent notices
98
+ stating that you changed the files and the date of any change.
99
+
100
+ b) You must cause any work that you distribute or publish, that in
101
+ whole or in part contains or is derived from the Program or any
102
+ part thereof, to be licensed as a whole at no charge to all third
103
+ parties under the terms of this License.
104
+
105
+ c) If the modified program normally reads commands interactively
106
+ when run, you must cause it, when started running for such
107
+ interactive use in the most ordinary way, to print or display an
108
+ announcement including an appropriate copyright notice and a
109
+ notice that there is no warranty (or else, saying that you provide
110
+ a warranty) and that users may redistribute the program under
111
+ these conditions, and telling the user how to view a copy of this
112
+ License. (Exception: if the Program itself is interactive but
113
+ does not normally print such an announcement, your work based on
114
+ the Program is not required to print an announcement.)
115
+
116
+ These requirements apply to the modified work as a whole. If
117
+ identifiable sections of that work are not derived from the Program,
118
+ and can be reasonably considered independent and separate works in
119
+ themselves, then this License, and its terms, do not apply to those
120
+ sections when you distribute them as separate works. But when you
121
+ distribute the same sections as part of a whole which is a work based
122
+ on the Program, the distribution of the whole must be on the terms of
123
+ this License, whose permissions for other licensees extend to the
124
+ entire whole, and thus to each and every part regardless of who wrote it.
125
+
126
+ Thus, it is not the intent of this section to claim rights or contest
127
+ your rights to work written entirely by you; rather, the intent is to
128
+ exercise the right to control the distribution of derivative or
129
+ collective works based on the Program.
130
+
131
+ In addition, mere aggregation of another work not based on the Program
132
+ with the Program (or with a work based on the Program) on a volume of
133
+ a storage or distribution medium does not bring the other work under
134
+ the scope of this License.
135
+
136
+ 3. You may copy and distribute the Program (or a work based on it,
137
+ under Section 2) in object code or executable form under the terms of
138
+ Sections 1 and 2 above provided that you also do one of the following:
139
+
140
+ a) Accompany it with the complete corresponding machine-readable
141
+ source code, which must be distributed under the terms of Sections
142
+ 1 and 2 above on a medium customarily used for software interchange; or,
143
+
144
+ b) Accompany it with a written offer, valid for at least three
145
+ years, to give any third party, for a charge no more than your
146
+ cost of physically performing source distribution, a complete
147
+ machine-readable copy of the corresponding source code, to be
148
+ distributed under the terms of Sections 1 and 2 above on a medium
149
+ customarily used for software interchange; or,
150
+
151
+ c) Accompany it with the information you received as to the offer
152
+ to distribute corresponding source code. (This alternative is
153
+ allowed only for noncommercial distribution and only if you
154
+ received the program in object code or executable form with such
155
+ an offer, in accord with Subsection b above.)
156
+
157
+ The source code for a work means the preferred form of the work for
158
+ making modifications to it. For an executable work, complete source
159
+ code means all the source code for all modules it contains, plus any
160
+ associated interface definition files, plus the scripts used to
161
+ control compilation and installation of the executable. However, as a
162
+ special exception, the source code distributed need not include
163
+ anything that is normally distributed (in either source or binary
164
+ form) with the major components (compiler, kernel, and so on) of the
165
+ operating system on which the executable runs, unless that component
166
+ itself accompanies the executable.
167
+
168
+ If distribution of executable or object code is made by offering
169
+ access to copy from a designated place, then offering equivalent
170
+ access to copy the source code from the same place counts as
171
+ distribution of the source code, even though third parties are not
172
+ compelled to copy the source along with the object code.
173
+
174
+ 4. You may not copy, modify, sublicense, or distribute the Program
175
+ except as expressly provided under this License. Any attempt
176
+ otherwise to copy, modify, sublicense or distribute the Program is
177
+ void, and will automatically terminate your rights under this License.
178
+ However, parties who have received copies, or rights, from you under
179
+ this License will not have their licenses terminated so long as such
180
+ parties remain in full compliance.
181
+
182
+ 5. You are not required to accept this License, since you have not
183
+ signed it. However, nothing else grants you permission to modify or
184
+ distribute the Program or its derivative works. These actions are
185
+ prohibited by law if you do not accept this License. Therefore, by
186
+ modifying or distributing the Program (or any work based on the
187
+ Program), you indicate your acceptance of this License to do so, and
188
+ all its terms and conditions for copying, distributing or modifying
189
+ the Program or works based on it.
190
+
191
+ 6. Each time you redistribute the Program (or any work based on the
192
+ Program), the recipient automatically receives a license from the
193
+ original licensor to copy, distribute or modify the Program subject to
194
+ these terms and conditions. You may not impose any further
195
+ restrictions on the recipients' exercise of the rights granted herein.
196
+ You are not responsible for enforcing compliance by third parties to
197
+ this License.
198
+
199
+ 7. If, as a consequence of a court judgment or allegation of patent
200
+ infringement or for any other reason (not limited to patent issues),
201
+ conditions are imposed on you (whether by court order, agreement or
202
+ otherwise) that contradict the conditions of this License, they do not
203
+ excuse you from the conditions of this License. If you cannot
204
+ distribute so as to satisfy simultaneously your obligations under this
205
+ License and any other pertinent obligations, then as a consequence you
206
+ may not distribute the Program at all. For example, if a patent
207
+ license would not permit royalty-free redistribution of the Program by
208
+ all those who receive copies directly or indirectly through you, then
209
+ the only way you could satisfy both it and this License would be to
210
+ refrain entirely from distribution of the Program.
211
+
212
+ If any portion of this section is held invalid or unenforceable under
213
+ any particular circumstance, the balance of the section is intended to
214
+ apply and the section as a whole is intended to apply in other
215
+ circumstances.
216
+
217
+ It is not the purpose of this section to induce you to infringe any
218
+ patents or other property right claims or to contest validity of any
219
+ such claims; this section has the sole purpose of protecting the
220
+ integrity of the free software distribution system, which is
221
+ implemented by public license practices. Many people have made
222
+ generous contributions to the wide range of software distributed
223
+ through that system in reliance on consistent application of that
224
+ system; it is up to the author/donor to decide if he or she is willing
225
+ to distribute software through any other system and a licensee cannot
226
+ impose that choice.
227
+
228
+ This section is intended to make thoroughly clear what is believed to
229
+ be a consequence of the rest of this License.
230
+
231
+ 8. If the distribution and/or use of the Program is restricted in
232
+ certain countries either by patents or by copyrighted interfaces, the
233
+ original copyright holder who places the Program under this License
234
+ may add an explicit geographical distribution limitation excluding
235
+ those countries, so that distribution is permitted only in or among
236
+ countries not thus excluded. In such case, this License incorporates
237
+ the limitation as if written in the body of this License.
238
+
239
+ 9. The Free Software Foundation may publish revised and/or new versions
240
+ of the General Public License from time to time. Such new versions will
241
+ be similar in spirit to the present version, but may differ in detail to
242
+ address new problems or concerns.
243
+
244
+ Each version is given a distinguishing version number. If the Program
245
+ specifies a version number of this License which applies to it and "any
246
+ later version", you have the option of following the terms and conditions
247
+ either of that version or of any later version published by the Free
248
+ Software Foundation. If the Program does not specify a version number of
249
+ this License, you may choose any version ever published by the Free Software
250
+ Foundation.
251
+
252
+ 10. If you wish to incorporate parts of the Program into other free
253
+ programs whose distribution conditions are different, write to the author
254
+ to ask for permission. For software which is copyrighted by the Free
255
+ Software Foundation, write to the Free Software Foundation; we sometimes
256
+ make exceptions for this. Our decision will be guided by the two goals
257
+ of preserving the free status of all derivatives of our free software and
258
+ of promoting the sharing and reuse of software generally.
259
+
260
+ NO WARRANTY
261
+
262
+ 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
263
+ FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
264
+ OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
265
+ PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
266
+ OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
267
+ MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
268
+ TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
269
+ PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
270
+ REPAIR OR CORRECTION.
271
+
272
+ 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
273
+ WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
274
+ REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
275
+ INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
276
+ OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
277
+ TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
278
+ YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
279
+ PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
280
+ POSSIBILITY OF SUCH DAMAGES.
281
+
data/README ADDED
@@ -0,0 +1,68 @@
1
+ $Id: README 2484 2006-05-12 16:55:59Z francis $
2
+
3
+ = RUBY/EventMachine
4
+
5
+ Homepage:: http://rubyeventmachine.com
6
+ Copyright:: (C) 2006 by Francis Cianfrocca. All Rights Reserved.
7
+ Email:: gmail address: garbagecat10
8
+
9
+ This program is made available under the terms of the Lesser-GPL version 2.
10
+ See EventMachine and EventMachine::Connection for documentation and
11
+ usage examples.
12
+
13
+ EventMachine implements a fast, single-threaded engine for arbitrary network
14
+ communications. It's extremely easy to use in Ruby. EventMachine wraps all
15
+ interactions with IP sockets, allowing programs to concentrate on the
16
+ implementation of network protocols. It can be used to create both network
17
+ servers and clients. To create a server or client, a Ruby program only needs
18
+ to specify the IP address and port, and provide a Module that implements the
19
+ communications protocol. Implementations of several standard network protocols
20
+ are provided with the package, primarily to serve as examples. The real goal
21
+ of EventMachine is to enable programs to easily interface with other programs
22
+ using TCP/IP, especially if custom protocols are required.
23
+
24
+ A Ruby program uses EventMachine by registering the addresses and ports of
25
+ network servers and clients, and then entering an event-handling loop.
26
+ EventMachine contains glue code in Ruby which will execute callbacks to
27
+ user-supplied code for all significant events occurring in the clients
28
+ and servers. These events include connection acceptance, startup, data-receipt,
29
+ shutdown, and timer events. Arbitrary processing can be performed by user code
30
+ during event callbacks, including sending data to one or more remote network
31
+ peers, startup and shutdown of network connections, and installation of new
32
+ event handlers.
33
+
34
+ The EventMachine implements a very familiar model for network programming.
35
+ It emphasizes: 1) the maximum possible isolation of user code from network
36
+ objects like sockets; 2) maximum performance and scalability; and 3) extreme
37
+ ease-of-use for user code. It attempts to provide a higher-level interface
38
+ than similar projects which expose a variety of low-level event-handling
39
+ and networking objects to Ruby programs.
40
+
41
+ The design and implementation of EventMachine grows out of nearly ten years
42
+ of experience writing high-performance, high-scaling network server applications.
43
+ We have taken particular account of the challenges and lessons described as
44
+ the "C10K problem" by Dan Kegel and others.
45
+
46
+ EventMachine consists of an extension library written in C++ (which can be
47
+ accessed from languages other than Ruby), and a Ruby module which can be dropped
48
+ into user programs. The current implementation uses the <tt>select(2)</tt> system call
49
+ and may be used on a range of Unix-like systems. A future version of EventMachine
50
+ for Linux will use <tt>epoll(4)</tt> and will thus require a Linux 2.6 kernel.
51
+ Here's a fully-functional echo server written with EventMachine:
52
+
53
+ require 'rubygems'
54
+ require 'eventmachine'
55
+
56
+ module EchoServer
57
+ def receive_data data
58
+ send_data ">>>you sent: #{data}"
59
+ close_connection if data =~ /quit/i
60
+ end
61
+ end
62
+
63
+ EventMachine::run {
64
+ EventMachine::start_server "192.168.0.100", 8081, EchoServer
65
+ }
66
+
67
+
68
+ # vim: sts=2 sw=2 ts=4 et ai tw=77
data/RELEASE_NOTES ADDED
@@ -0,0 +1,59 @@
1
+ $Id: RELEASE_NOTES 2477 2006-05-11 13:22:39Z francis $
2
+
3
+ RUBY/EventMachine RELEASE NOTES
4
+
5
+ --------------------------------------------------
6
+ Version: 0.5.2, released 05May06
7
+ Made several nonvisible improvements to the Windows
8
+ implementation.
9
+ Added an exception-handling patch contributed by Jeff Rose, jeff@rosejn.net.
10
+ Added a dir-config patch contributed anonymously.
11
+ Supported builds on Solaris.
12
+
13
+ --------------------------------------------------
14
+ Version: 0.5.1, released 05May06
15
+ Made it possible to pass a Class rather than a Module
16
+ to a protocol handler.
17
+ Added Windows port.
18
+
19
+ --------------------------------------------------
20
+ Version: 0.5.0, released 30Apr06
21
+ Added a preliminary SSL/TLS extension. This will probably
22
+ change over the next few releases.
23
+
24
+ --------------------------------------------------
25
+ Version: 0.4.5, released 29Apr06
26
+ Changed ext files so the ruby.h is installed after unistd.h
27
+ otherwise it doesn't compile on gcc 4.1
28
+
29
+ --------------------------------------------------
30
+ Version: 0.4.2, released 19Apr06
31
+ Changed the Ruby-glue so the extension will play nicer
32
+ in the sandbox with Ruby threads.
33
+ Added an EventMachine::run_without_threads API to
34
+ switch off the thread-awareness for better performance
35
+ in programs that do not spin any Ruby threads.
36
+
37
+ --------------------------------------------------
38
+ Version: 0.4.1, released 15Apr06
39
+ Reworked the shared-object interface to make it easier to
40
+ use EventMachine from languages other than Ruby.
41
+
42
+ --------------------------------------------------
43
+ Version: 0.3.2, released 12Apr06
44
+ Added support for a user-supplied block in EventMachine#connect.
45
+
46
+ --------------------------------------------------
47
+ Version: 0.3.1, released 11Apr06
48
+ Fixed bug that prevented EventMachine from being run multiple
49
+ times in a single process.
50
+
51
+ --------------------------------------------------
52
+ Version: 0.3.0, released 10Apr06
53
+ Added method EventHandler::Connection::post_init
54
+
55
+ --------------------------------------------------
56
+ Version: 0.2.0, released 10Apr06
57
+ Added method EventHandler::stop
58
+
59
+
@@ -0,0 +1,806 @@
1
+ # $Id: eventmachine.rb 2469 2006-05-10 18:11:10Z francis $
2
+ #
3
+ # Author:: blackhedd (gmail address: garbagecat20).
4
+ # Date:: 8 Apr 2006
5
+ #
6
+ # Copyright (C) 2006 by Francis Cianfrocca. All Rights Reserved.
7
+ #
8
+ # This program is made available under the terms of the GPL version 2.
9
+ #
10
+ # See EventMachine and EventMachine::Connection for documentation and
11
+ # usage examples.
12
+ #
13
+ #----------------------------------------------------------------------------
14
+ #
15
+ # Copyright (C) 2006 by Francis Cianfrocca. All Rights Reserved.
16
+ #
17
+ # Gmail: garbagecat10
18
+ #
19
+ # This program is free software; you can redistribute it and/or modify
20
+ # it under the terms of the GNU General Public License as published by
21
+ # the Free Software Foundation; either version 2 of the License, or
22
+ # (at your option) any later version.
23
+ #
24
+ # This program is distributed in the hope that it will be useful,
25
+ # but WITHOUT ANY WARRANTY; without even the implied warranty of
26
+ # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
27
+ # GNU General Public License for more details.
28
+ #
29
+ # You should have received a copy of the GNU General Public License
30
+ # along with this program; if not, write to the Free Software
31
+ # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
32
+ #
33
+ #---------------------------------------------------------------------------
34
+ #
35
+ #
36
+
37
+ require 'rubyeventmachine'
38
+
39
+ # == Introduction
40
+ # EventMachine provides a fast, lightweight framework for implementing
41
+ # Ruby programs that can use the network to communicate with other
42
+ # processes. Using EventMachine, Ruby programmers can easily connect
43
+ # to remote servers and act as servers themselves. EventMachine does not
44
+ # supplant the Ruby IP libraries. It does provide an alternate technique
45
+ # for those applications requiring better performance, scalability,
46
+ # and discipline over the behavior of network sockets, than is easily
47
+ # obtainable using the built-in libraries, especially in applications
48
+ # which are structurally well-suited for the event-driven programming model.
49
+ #
50
+ # EventMachine provides a perpetual event-loop which your programs can
51
+ # start and stop. Within the event loop, TCP network connections are
52
+ # initiated and accepted, based on EventMachine methods called by your
53
+ # program. You also define callback methods which are called by EventMachine
54
+ # when events of interest occur within the event-loop.
55
+ #
56
+ # User programs will be called back when the following events occur:
57
+ # * When the event loop accepts network connections from remote peers
58
+ # * When data is received from network connections
59
+ # * When connections are closed, either by the local or the remote side
60
+ # * When user-defined timers expire
61
+ #
62
+ # == Usage example
63
+ #
64
+ # Here's a fully-functional echo server implemented in EventMachine:
65
+ #
66
+ # require 'rubygems'
67
+ # require 'eventmachine'
68
+ #
69
+ # module EchoServer
70
+ # def receive_data data
71
+ # send_data ">>>you sent: #{data}"
72
+ # close_connection if data =~ /quit/i
73
+ # end
74
+ # end
75
+ #
76
+ # EventMachine::run {
77
+ # EventMachine::start_server "192.168.0.100", 8081, EchoServer
78
+ # }
79
+ #
80
+ # What's going on here? Well, we have defined the module EchoServer to
81
+ # implement the semantics of the echo protocol (more about that shortly).
82
+ # The last three lines invoke the event-machine itself, which runs forever
83
+ # unless one of your callbacks terminates it. The block that you supply
84
+ # to EventMachine::run contains code that runs immediately after the event
85
+ # machine is initialized and before it starts looping. This is the place
86
+ # to open up a TCP server by specifying the address and port it will listen
87
+ # on, together with the module that will process the data.
88
+ #
89
+ # Our EchoServer is extremely simple as the echo protocol doesn't require
90
+ # much work. Basically you want to send back to the remote peer whatever
91
+ # data it sends you. We'll dress it up with a little extra text to make it
92
+ # interesting. Also, we'll close the connection in case the received data
93
+ # contains the word "quit."
94
+ #
95
+ # So what about this module EchoServer? Well, whenever a network connection
96
+ # (either a client or a server) starts up, EventMachine instantiates an anonymous
97
+ # class, that your module has been mixed into. Exactly one of these class
98
+ # instances is created for each connection. Whenever an event occurs on a
99
+ # given connection, its corresponding object automatically calls specific
100
+ # instance methods which your module may redefine. The code in your module
101
+ # always runs in the context of a class instance, so you can create instance
102
+ # variables as you wish and they will be carried over to other callbacks
103
+ # made on that same connection.
104
+ #
105
+ # Looking back up at EchoServer, you can see that we've defined the method
106
+ # receive_data which (big surprise) is called whenever data has been received
107
+ # from the remote end of the connection. Very simple. We get the data
108
+ # (a String object) and can do whatever we wish with it. In this case,
109
+ # we use the method send_data to return the received data to the caller,
110
+ # with some extra text added in. And if the user sends the word "quit,"
111
+ # we'll close the connection with (naturally) close_connection.
112
+ # (Notice that closing the connection doesn't terminate the processing loop,
113
+ # or change the fact that your echo server is still accepting connections!)
114
+ #
115
+ #
116
+ # == Questions and Futures
117
+ # Encryption: EventMachine needs the capability to run SSL/TLS on any
118
+ # of its clients and servers. Coming soon.
119
+ #
120
+ # <tt>epoll(4):</tt> EventMachine currently is based on the <tt>select(2)</tt>
121
+ # system call in order to be compatible with the widest variety of platforms,
122
+ # but it would be interesting to re-base it on <tt>epoll(4).</tt>
123
+ # While requiring a Linux 2.6 kernel, this might possibly give much better
124
+ # performance and scalability. EventMachine's C++ antecedents already work
125
+ # with <tt>kqueue</tt> from the BSD world, but it's not yet clear that this
126
+ # is worth doing. Depends on how many people ask for it.
127
+ #
128
+ # Would it be useful for EventMachine to incorporate the Observer pattern
129
+ # and make use of the corresponding Ruby <tt>observer</tt> package?
130
+ # Interesting thought.
131
+ #
132
+ #
133
+ module EventMachine
134
+
135
+
136
+ # EventMachine::run initializes and runs an event loop.
137
+ # This method only returns if user-callback code calls stop_event_loop.
138
+ # Use the supplied block to define your clients and servers.
139
+ # The block is called by EventMachine::run immediately after initializing
140
+ # its internal event loop but <i>before</i> running the loop.
141
+ # Therefore this block is the right place to call start_server if you
142
+ # want to accept connections from remote clients.
143
+ #
144
+ # For programs that are structured as servers, it's usually appropriate
145
+ # to start an event loop by calling EventMachine::run, and let it
146
+ # run forever. It's also possible to use EventMachine::run to make a single
147
+ # client-connection to a remote server, process the data flow from that
148
+ # single connection, and then call stop_event_loop to force EventMachine::run
149
+ # to return. Your program will then continue from the point immediately
150
+ # following the call to EventMachine::run.
151
+ #
152
+ # You can of course do both client and servers simultaneously in the same program.
153
+ # One of the strengths of the event-driven programming model is that the
154
+ # handling of network events on many different connections will be interleaved,
155
+ # and scheduled according to the actual events themselves. This maximizes
156
+ # efficiency.
157
+ #
158
+ # === Server usage example
159
+ #
160
+ # See the text at the top of this file for an example of an echo server.
161
+ #
162
+ # === Client usage example
163
+ #
164
+ # See the description of stop_event_loop for an extremely simple client example.
165
+ #
166
+ #--
167
+ # Obsoleted the use_threads mechanism.
168
+ #
169
+ def EventMachine::run &block
170
+ #def EventMachine::run use_threads = true, &block
171
+ @conns = {}
172
+ @acceptors = {}
173
+ @timers = {}
174
+ initialize_event_machine
175
+ block and add_timer 0, block
176
+ #use_threads ? run_machine : run_machine_without_threads
177
+ run_machine
178
+ release_machine
179
+ end
180
+
181
+ # +deprecated+
182
+ #--
183
+ # EventMachine#run_without_threads is semantically identical
184
+ # to EventMachine#run, but it runs somewhat faster.
185
+ # However, it must not be used in applications that spin
186
+ # Ruby threads.
187
+ def EventMachine::run_without_threads &block
188
+ #EventMachine::run false, &block
189
+ EventMachine::run &block
190
+ end
191
+
192
+ # EventMachine#add_timer adds a one-shot timer to the event loop.
193
+ # Call it with one or two parameters. The first parameters is a delay-time
194
+ # expressed in <i>seconds</i> (not milliseconds). The second parameter, if
195
+ # present, must be a proc object. If a proc object is not given, then you
196
+ # can also simply pass a block to the method call.
197
+ #
198
+ # EventMachine#add_timer may be called from the block passed to EventMachine#run
199
+ # or from any callback method. It schedules execution of the proc or block
200
+ # passed to add_timer, after the passage of an interval of time equal to
201
+ # <i>at least</i> the number of seconds specified in the first parameter to
202
+ # the call.
203
+ #
204
+ # EventMachine#add_timer is a <i>non-blocking</i> call. Callbacks can and will
205
+ # be called during the interval of time that the timer is in effect.
206
+ # There is no built-in limit to the number of timers that can be outstanding at
207
+ # any given time.
208
+ #
209
+ # === Usage example
210
+ #
211
+ # This example shows how easy timers are to use. Observe that two timers are
212
+ # initiated simultaneously. Also, notice that the event loop will continue
213
+ # to run even after the second timer event is processed, since there was
214
+ # no call to EventMachine#stop_event_loop. There will be no activity, of
215
+ # course, since no network clients or servers are defined. Stop the program
216
+ # with Ctrl-C.
217
+ #
218
+ # require 'rubygems'
219
+ # require 'eventmachine'
220
+ #
221
+ # EventMachine::run {
222
+ # puts "Starting the run now: #{Time.now}"
223
+ # EventMachine::add_timer 5, proc { puts "Executing timer event: #{Time.now}" }
224
+ # EventMachine::add_timer( 10 ) { puts "Executing timer event: #{Time.now}" }
225
+ # }
226
+ #
227
+ #
228
+ def EventMachine::add_timer *args, &block
229
+ interval = args.shift
230
+ code = args.shift || block
231
+ if code
232
+ # check too many timers!
233
+ s = add_oneshot_timer interval
234
+ @timers[s] = code
235
+ end
236
+ end
237
+
238
+ # EventMachine#add_periodic_timer adds a periodic timer to the event loop.
239
+ # It takes the same parameters as the one-shot timer method, EventMachine#add_timer.
240
+ # This method schedules execution of the given block repeatedly, at intervals
241
+ # of time <i>at least</i> as great as the number of seconds given in the first
242
+ # parameter to the call.
243
+ #
244
+ # === Usage example
245
+ #
246
+ # The following sample program will write a dollar-sign to stderr every five seconds.
247
+ # (Of course if the program defined network clients and/or servers, they would
248
+ # be doing their work while the periodic timer is counting off.)
249
+ #
250
+ # EventMachine::run {
251
+ # EventMachine::add_periodic_timer( 5 ) { $stderr.write "$" }
252
+ # }
253
+ #
254
+ def EventMachine::add_periodic_timer *args, &block
255
+ interval = args.shift
256
+ code = args.shift || block
257
+ if code
258
+ block_1 = proc {
259
+ code.call
260
+ EventMachine::add_periodic_timer interval, code
261
+ }
262
+ add_timer interval, block_1
263
+ end
264
+ end
265
+
266
+
267
+ # stop_event_loop may called from within a callback method
268
+ # while EventMachine's processing loop is running.
269
+ # It causes the processing loop to stop executing, which
270
+ # will cause all open connections and accepting servers
271
+ # to be run down and closed. <i>Callbacks for connection-termination
272
+ # will be called</i> as part of the processing of stop_event_loop.
273
+ # (There currently is no option to panic-stop the loop without
274
+ # closing connections.) When all of this processing is complete,
275
+ # the call to EventMachine::run which started the processing loop
276
+ # will return and program flow will resume from the statement
277
+ # following EventMachine::run call.
278
+ #
279
+ # === Usage example
280
+ #
281
+ # require 'rubygems'
282
+ # require 'eventmachine'
283
+ #
284
+ # module Redmond
285
+ #
286
+ # def post_init
287
+ # puts "We're sending a dumb HTTP request to the remote peer."
288
+ # send_data "GET / HTTP/1.1\r\nHost: www.microsoft.com\r\n\r\n"
289
+ # end
290
+ #
291
+ # def receive_data data
292
+ # puts "We received #{data.length} bytes from the remote peer."
293
+ # puts "We're going to stop the event loop now."
294
+ # EventMachine::stop_event_loop
295
+ # end
296
+ #
297
+ # def unbind
298
+ # puts "A connection has terminated."
299
+ # end
300
+ #
301
+ # end
302
+ #
303
+ # puts "We're starting the event loop now."
304
+ # EventMachine::run {
305
+ # EventMachine::connect "www.microsoft.com", 80, Redmond
306
+ # }
307
+ # puts "The event loop has stopped."
308
+ #
309
+ # This program will produce approximately the following output:
310
+ #
311
+ # We're starting the event loop now.
312
+ # We're sending a dumb HTTP request to the remote peer.
313
+ # We received 1440 bytes from the remote peer.
314
+ # We're going to stop the event loop now.
315
+ # A connection has terminated.
316
+ # The event loop has stopped.
317
+ #
318
+ #
319
+ def EventMachine::stop_event_loop
320
+ EventMachine::stop
321
+ end
322
+
323
+ # EventMachine::start_server initiates a TCP server (socket
324
+ # acceptor) on the specified IP address and port.
325
+ # The IP address must be valid on the machine where the program
326
+ # runs, and the process must be privileged enough to listen
327
+ # on the specified port (on Unix-like systems, superuser privileges
328
+ # are usually required to listen on any port lower than 1024).
329
+ # Only one listener may be running on any given address/port
330
+ # combination. start_server will fail if the given address and port
331
+ # are already listening on the machine, either because of a prior call
332
+ # to start_server or some unrelated process running on the machine.
333
+ # If start_server succeeds, the new network listener becomes active
334
+ # immediately and starts accepting connections from remote peers,
335
+ # and these connections generate callback events that are processed
336
+ # by the code specified in the handler parameter to start_server.
337
+ #
338
+ # The optional handler which is passed to start_server is the key
339
+ # to EventMachine's ability to handle particular network protocols.
340
+ # The handler parameter passed to start_server must be a Ruby Module
341
+ # that you must define. When the network server that is started by
342
+ # start_server accepts a new connection, it instantiates a new
343
+ # object of an anonymous class that is inherited from EventMachine::Connection,
344
+ # <i>into which the methods from your handler have been mixed.</i>
345
+ # Your handler module may redefine any of the methods in EventMachine::Connection
346
+ # in order to implement the specific behavior of the network protocol.
347
+ #
348
+ # Callbacks invoked in response to network events <i>always</i> take place
349
+ # within the execution context of the object derived from EventMachine::Connection
350
+ # extended by your handler module. There is one object per connection, and
351
+ # all of the callbacks invoked for a particular connection take the form
352
+ # of instance methods called against the corresponding EventMachine::Connection
353
+ # object. Therefore, you are free to define whatever instance variables you
354
+ # wish, in order to contain the per-connection state required by the network protocol you are
355
+ # implementing.
356
+ #
357
+ # start_server is often called inside the block passed to EventMachine::run,
358
+ # but it can be called from any EventMachine callback. start_server will fail
359
+ # unless the EventMachine event loop is currently running (which is why
360
+ # it's often called in the block suppled to EventMachine::run).
361
+ #
362
+ # You may call start_server any number of times to start up network
363
+ # listeners on different address/port combinations. The servers will
364
+ # all run simultaneously. More interestingly, each individual call to start_server
365
+ # can specify a different handler module and thus implement a different
366
+ # network protocol from all the others.
367
+ #
368
+ # === Usage example
369
+ # Here is an example of a server that counts lines of input from the remote
370
+ # peer and sends back the total number of lines received, after each line.
371
+ # Try the example with more than one client connection opened via telnet,
372
+ # and you will see that the line count increments independently on each
373
+ # of the client connections. Also very important to note, is that the
374
+ # handler for the receive_data function, which our handler redefines, may
375
+ # not assume that the data it receives observes any kind of message boundaries.
376
+ # Also, to use this example, be sure to change the server and port parameters
377
+ # to the start_server call to values appropriate for your environment.
378
+ #
379
+ # require 'rubygems'
380
+ # require 'eventmachine'
381
+ #
382
+ # module LineCounter
383
+ #
384
+ # MaxLinesPerConnection = 10
385
+ #
386
+ # def post_init
387
+ # puts "Received a new connection"
388
+ # @data_received = ""
389
+ # @line_count = 0
390
+ # end
391
+ #
392
+ # def receive_data data
393
+ # @data_received << data
394
+ # while @data_received.slice!( /^[^\n]*[\n]/m )
395
+ # @line_count += 1
396
+ # send_data "received #{@line_count} lines so far\r\n"
397
+ # @line_count == MaxLinesPerConnection and close_connection_after_writing
398
+ # end
399
+ # end
400
+ #
401
+ # end # module LineCounter
402
+ #
403
+ # EventMachine::run {
404
+ # host,port = "192.168.0.100", 8090
405
+ # EventMachine::start_server host, port, LineCounter
406
+ # puts "Now accepting connections on address #{host}, port #{port}..."
407
+ # EventMachine::add_periodic_timer( 10 ) { $stderr.write "*" }
408
+ # }
409
+ #
410
+ #
411
+ def EventMachine::start_server server, port, handler=nil
412
+ klass = if (handler and handler.is_a?(Class))
413
+ handler
414
+ else
415
+ Class.new( Connection ) {handler and include handler}
416
+ end
417
+
418
+ s = start_tcp_server server, port
419
+ @acceptors[s] = klass
420
+ end
421
+
422
+ # EventMachine#connect initiates a TCP connection to a remote
423
+ # server and sets up event-handling for the connection.
424
+ # You can call EventMachine#connect in the block supplied
425
+ # to EventMachine#run or in any callback method.
426
+ #
427
+ # EventMachine#connect takes the IP address (or hostname) and
428
+ # port of the remote server you want to connect to.
429
+ # It also takes an optional handler Module which you must define, that
430
+ # contains the callbacks that will be invoked by the event loop
431
+ # on behalf of the connection.
432
+ #
433
+ # See the description of EventMachine#start_server for a discussion
434
+ # of the handler Module. All of the details given in that description
435
+ # apply for connections created with EventMachine#connect.
436
+ #
437
+ # === Usage Example
438
+ #
439
+ # Here's a program which connects to a web server, sends a naive
440
+ # request, parses the HTTP header of the response, and then
441
+ # (antisocially) ends the event loop, which automatically drops the connection
442
+ # (and incidentally calls the connection's unbind method).
443
+ #
444
+ # require 'rubygems'
445
+ # require 'eventmachine'
446
+ #
447
+ # module DumbHttpClient
448
+ #
449
+ # def post_init
450
+ # send_data "GET / HTTP/1.1\r\nHost: _\r\n\r\n"
451
+ # @data = ""
452
+ # end
453
+ #
454
+ # def receive_data data
455
+ # @data << data
456
+ # if @data =~ /[\n][\r]*[\n]/m
457
+ # puts "RECEIVED HTTP HEADER:"
458
+ # $`.each {|line| puts ">>> #{line}" }
459
+ #
460
+ # puts "Now we'll terminate the loop, which will also close the connection"
461
+ # EventMachine::stop_event_loop
462
+ # end
463
+ # end
464
+ #
465
+ # def unbind
466
+ # puts "A connection has terminated"
467
+ # end
468
+ #
469
+ # end # DumbHttpClient
470
+ #
471
+ #
472
+ # EventMachine::run {
473
+ # EventMachine::connect "www.bayshorenetworks.com", 80, DumbHttpClient
474
+ # }
475
+ # puts "The event loop has ended"
476
+ #
477
+ #
478
+ # There are times when it's more convenient to define a protocol handler
479
+ # as a Class rather than a Module. Here's how to do this:
480
+ #
481
+ # class MyProtocolHandler < EventMachine::Connection
482
+ # def initialize *args
483
+ # super
484
+ # # whatever else you want to do here
485
+ # end
486
+ #
487
+ # #.......your other class code
488
+ # end # class MyProtocolHandler
489
+ #
490
+ # If you do this, then an instance of your class will be instantiated to handle
491
+ # every network connection created by your code or accepted by servers that you
492
+ # create. If you redefine #post_init in your protocol-handler class, your
493
+ # #post_init method will be called _inside_ the call to #super that you will
494
+ # make in your #initialize method (if you provide one).
495
+ #
496
+ #--
497
+ # EventMachine::connect initiates a TCP connection to a remote
498
+ # server and sets up event-handling for the connection.
499
+ # It internally creates an object that should not be handled
500
+ # by the caller. HOWEVER, it's often convenient to get the
501
+ # object to set up interfacing to other objects in the system.
502
+ # We return the newly-created anonymous-class object to the caller.
503
+ # It's expected that a considerable amount of code will depend
504
+ # on this behavior, so don't change it.
505
+ #
506
+ # Ok, added support for a user-defined block, 13Apr06.
507
+ # This leads us to an interesting choice because of the
508
+ # presence of the post_init call, which happens in the
509
+ # initialize method of the new object. We call the user's
510
+ # block and pass the new object to it. This is a great
511
+ # way to do protocol-specific initiation. It happens
512
+ # AFTER post_init has been called on the object, which I
513
+ # certainly hope is the right choice.
514
+ # Don't change this lightly, because accepted connections
515
+ # are different from connected ones and we don't want
516
+ # to have them behave differently with respect to post_init
517
+ # if at all possible.
518
+ #
519
+ def EventMachine::connect server, port, handler=nil
520
+
521
+ klass = if (handler and handler.is_a?(Class))
522
+ handler
523
+ else
524
+ Class.new( Connection ) {handler and include handler}
525
+ end
526
+
527
+ s = connect_server server, port
528
+ c = klass.new s
529
+ @conns[s] = c
530
+ block_given? and yield c
531
+ c
532
+ end
533
+
534
+
535
+ # EventMachine#open_datagram_socket is for support of UDP-based
536
+ # protocols. Its usage is similar to that of EventMachine#start_server.
537
+ # It takes three parameters: an IP address (which must be valid
538
+ # on the machine which executes the method), a port number,
539
+ # and an optional Module name which will handle the data.
540
+ # This method will create a new UDP (datagram) socket and
541
+ # bind it to the address and port that you specify.
542
+ # The normal callbacks (see EventMachine#start_server) will
543
+ # be called as events of interest occur on the newly-created
544
+ # socket, but there are some differences in how they behave.
545
+ #
546
+ # Connection#receive_data will be called when a datagram packet
547
+ # is received on the socket, but unlike TCP sockets, the message
548
+ # boundaries of the received data will be respected. In other words,
549
+ # if the remote peer sent you a datagram of a particular size,
550
+ # you may rely on Connection#receive_data to give you the
551
+ # exact data in the packet, with the original data length.
552
+ # Also observe that Connection#receive_data may be called with a
553
+ # <i>zero-length</i> data payload, since empty datagrams are permitted
554
+ # in UDP.
555
+ #
556
+ # Connection#send_data is available with UDP packets as with TCP,
557
+ # but there is an important difference. Because UDP communications
558
+ # are <i>connectionless,</i> there is no implicit recipient for the packets you
559
+ # send. Ordinarily you must specify the recipient for each packet you send.
560
+ # However, EventMachine
561
+ # provides for the typical pattern of receiving a UDP datagram
562
+ # from a remote peer, performing some operation, and then sending
563
+ # one or more packets in response to the same remote peer.
564
+ # To support this model easily, just use Connection#send_data
565
+ # in the code that you supply for Connection:receive_data.
566
+ # EventMachine will
567
+ # provide an implicit return address for any messages sent to
568
+ # Connection#send_data within the context of a Connection#receive_data callback,
569
+ # and your response will automatically go to the correct remote peer.
570
+ # (TODO: Example-code needed!)
571
+ #
572
+ # Observe that the port number that you supply to EventMachine#open_datagram_socket
573
+ # may be zero. In this case, EventMachine will create a UDP socket
574
+ # that is bound to an <i>ephemeral</i> (not well-known) port.
575
+ # This is not appropriate for servers that must publish a well-known
576
+ # port to which remote peers may send datagrams. But it can be useful
577
+ # for clients that send datagrams to other servers.
578
+ # If you do this, you will receive any responses from the remote
579
+ # servers through the normal Connection#receive_data callback.
580
+ # Observe that you will probably have issues with firewalls blocking
581
+ # the ephemeral port numbers, so this technique is most appropriate for LANs.
582
+ # (TODO: Need an example!)
583
+ #
584
+ # If you wish to send datagrams to arbitrary remote peers (not
585
+ # necessarily ones that have sent data to which you are responding),
586
+ # then see Connection#send_datagram.
587
+ #
588
+ def self::open_datagram_socket address, port, handler=nil
589
+ s = open_udp_socket address, port
590
+ klass = Class.new( Connection ) {
591
+ handler and include handler
592
+ }
593
+ c = klass.new s
594
+ @conns[s] = c
595
+ block_given? and yield c
596
+ c
597
+ end
598
+
599
+
600
+ private
601
+ def EventMachine::event_callback conn_binding, opcode, data
602
+ case opcode
603
+ when ConnectionData
604
+ c = @conns[conn_binding] or raise ConnectionNotBound
605
+ c.receive_data data
606
+ when ConnectionUnbound
607
+ if c = @conns.delete( conn_binding )
608
+ c.unbind
609
+ elsif c = @acceptors.delete( conn_binding )
610
+ # no-op
611
+ else
612
+ raise ConnectionNotBound
613
+ end
614
+ when ConnectionAccepted
615
+ accep = @acceptors[conn_binding] or raise NoHandlerForAcceptedConnection
616
+ c = accep.new data
617
+ @conns[data] = c
618
+ when TimerFired
619
+ t = @timers.delete( data ) or raise UnknownTimerFired
620
+ t.call
621
+ end
622
+ end
623
+
624
+
625
+
626
+ # EventMachine::Connection is a class that is instantiated
627
+ # by EventMachine's processing loop whenever a new connection
628
+ # is created. (New connections can be either initiated locally
629
+ # to a remote server or accepted locally from a remote client.)
630
+ # When a Connection object is instantiated, it <i>mixes in</i>
631
+ # the functionality contained in the user-defined module
632
+ # specified in calls to EventMachine#connect or EventMachine#start_server.
633
+ # User-defined handler modules may redefine any or all of the standard
634
+ # methods defined here, as well as add arbitrary additional code
635
+ # that will also be mixed in.
636
+ #
637
+ # EventMachine manages one object inherited from EventMachine::Connection
638
+ # (and containing the mixed-in user code) for every network connection
639
+ # that is active at any given time.
640
+ # The event loop will automatically call methods on EventMachine::Connection
641
+ # objects whenever specific events occur on the corresponding connections,
642
+ # as described below.
643
+ #
644
+ # This class is never instantiated by user code, and does not publish an
645
+ # initialize method. The instance methods of EventMachine::Connection
646
+ # which may be called by the event loop are: post_init, receive_data,
647
+ # and unbind. All of the other instance methods defined here are called
648
+ # only by user code.
649
+ #
650
+ class Connection
651
+
652
+ def initialize sig #:nodoc:
653
+ @signature = sig
654
+ post_init
655
+ end
656
+
657
+ # EventMachine::Connection#post_init is called by the event loop
658
+ # immediately after the network connection has been established,
659
+ # and before resumption of the network loop.
660
+ # This method is generally not called by user code, but is called automatically
661
+ # by the event loop. The base-class implementation is a no-op.
662
+ # This is a very good place to initialize instance variables that will
663
+ # be used throughout the lifetime of the network connection.
664
+ #
665
+ def post_init
666
+ end
667
+
668
+ # EventMachine::Connection#receive_data is called by the event loop
669
+ # whenever data has been received by the network connection.
670
+ # It is never called by user code.
671
+ # receive_data is called with a single parameter, a String containing
672
+ # the network protocol data, which may of course be binary. You will
673
+ # generally redefine this method to perform your own processing of the incoming data.
674
+ #
675
+ # Here's a key point which is essential to understanding the event-driven
676
+ # programming model: <i>EventMachine knows absolutely nothing about the protocol
677
+ # which your code implements.</i> You must not make any assumptions about
678
+ # the size of the incoming data packets, or about their alignment on any
679
+ # particular intra-message or PDU boundaries (such as line breaks).
680
+ # receive_data can and will send you arbitrary chunks of data, with the
681
+ # only guarantee being that the data is presented to your code in the order
682
+ # it was collected from the network. Don't even assume that the chunks of
683
+ # data will correspond to network packets, as EventMachine can and will coalesce
684
+ # several incoming packets into one, to improve performance. The implication for your
685
+ # code is that you generally will need to implement some kind of a state machine
686
+ # in your redefined implementation of receive_data. For a better understanding
687
+ # of this, read through the examples of specific protocol handlers given
688
+ # elsewhere in this package. (STUB, WE MUST ADD THESE!)
689
+ #
690
+ # The base-class implementation of receive_data (which will be invoked if
691
+ # you don't redefine it) simply prints the size of each incoming data packet
692
+ # to stdout.
693
+ #
694
+ def receive_data data
695
+ puts "............>>>#{data.length}"
696
+ end
697
+
698
+ # EventMachine::Connection#unbind is called by the framework whenever a connection
699
+ # (either a server or client connection) is closed. The close can occur because
700
+ # your code intentionally closes it (see close_connection and close_connection_after_writing),
701
+ # because the remote peer closed the connection, or because of a network error.
702
+ # You may not assume that the network connection is still open and able to send or
703
+ # receive data when the callback to unbind is made. This is intended only to give
704
+ # you a chance to clean up associations your code may have made to the connection
705
+ # object while it was open.
706
+ #
707
+ def unbind
708
+ end
709
+
710
+ # EventMachine::Connection#close_connection is called only by user code, and never
711
+ # by the event loop. You may call this method against a connection object in any
712
+ # callback handler, whether or not the callback was made against the connection
713
+ # you want to close. close_connection <i>schedules</i> the connection to be closed
714
+ # at the next available opportunity within the event loop. You may not assume that
715
+ # the connection is closed when close_connection returns. In particular, the framework
716
+ # will callback the unbind method for the particular connection at a point shortly
717
+ # after you call close_connection. You may assume that the unbind callback will
718
+ # take place sometime after your call to close_connection completes. In other words,
719
+ # the unbind callback will not re-enter your code "inside" of your call to close_connection.
720
+ # However, it's not guaranteed that a future version of EventMachine will not change
721
+ # this behavior.
722
+ #
723
+ # close_connection will <i>silently discard</i> any outbound data which you have
724
+ # sent to the connection using EventMachine::Connection#send_data but which has not
725
+ # yet been sent across the network. If you want to avoid this behavior, use
726
+ # EventMachine::Connection#close_connection_after_writing.
727
+ #
728
+ def close_connection after_writing = false
729
+ EventMachine::close_connection @signature, after_writing
730
+ end
731
+
732
+ # EventMachine::Connection#close_connection_after_writing is a variant of close_connection.
733
+ # All of the descriptive comments given for close_connection also apply to
734
+ # close_connection_after_writing, <i>with one exception:</i> If the connection has
735
+ # outbound data sent using send_dat but which has not yet been sent across the network,
736
+ # close_connection_after_writing will schedule the connection to be closed <i>after</i>
737
+ # all of the outbound data has been safely written to the remote peer.
738
+ #
739
+ # Depending on the amount of outgoing data and the speed of the network,
740
+ # considerable time may elapse between your call to close_connection_after_writing
741
+ # and the actual closing of the socket (at which time the unbind callback will be called
742
+ # by the event loop). During this time, you <i>may not</i> call send_data to transmit
743
+ # additional data (that is, the connection is closed for further writes). In very
744
+ # rare cases, you may experience a receive_data callback after your call to close_connection_after_writing,
745
+ # depending on whether incoming data was in the process of being received on the connection
746
+ # at the moment when you called close_connection_after_writing. Your protocol handler must
747
+ # be prepared to properly deal with such data (probably by ignoring it).
748
+ #
749
+ def close_connection_after_writing
750
+ close_connection true
751
+ end
752
+
753
+ # EventMachine::Connection#send_data is only called by user code, never by
754
+ # the event loop. You call this method to send data to the remote end of the
755
+ # network connection. send_data is called with a single String argument, which
756
+ # may of course contain binary data. You can call send_data any number of times.
757
+ # send_data is an instance method of an object derived from EventMachine::Connection
758
+ # and containing your mixed-in handler code), so if you call it without qualification
759
+ # within a callback function, the data will be sent to the same network connection
760
+ # that generated the callback. Calling self.send_data is exactly equivalent.
761
+ #
762
+ # You can also call send_data to write to a connection <i>other than the one
763
+ # whose callback you are calling send_data from.</i> This is done by recording
764
+ # the value of the connection in any callback function (the value self), in any
765
+ # variable visible to other callback invocations on the same or different
766
+ # connection objects. (Need an example to make that clear.)
767
+ #
768
+ def send_data data
769
+ EventMachine::send_data @signature, data, data.length
770
+ end
771
+
772
+
773
+ def start_tls
774
+ EventMachine::start_tls @signature
775
+ end
776
+
777
+
778
+ # send_datagram is for sending UDP messages.
779
+ # This method may be called from any Connection object that refers
780
+ # to an open datagram socket (see EventMachine#open_datagram_socket).
781
+ # The method sends a UDP (datagram) packet containing the data you specify,
782
+ # to a remote peer specified by the IP address and port that you give
783
+ # as parameters to the method.
784
+ # Observe that you may send a zero-length packet (empty string).
785
+ # However, you may not send an arbitrarily-large data packet because
786
+ # your operating system will enforce a platform-specific limit on
787
+ # the size of the outbound packet. (Your kernel
788
+ # will respond in a platform-specific way if you send an overlarge
789
+ # packet: some will send a truncated packet, some will complain, and
790
+ # some will silently drop your request).
791
+ # On LANs, it's usually OK to send datagrams up to about 4000 bytes in length,
792
+ # but to be really safe, send messages smaller than the Ethernet-packet
793
+ # size (typically about 1400 bytes). Some very restrictive WANs
794
+ # will either drop or truncate packets larger than about 500 bytes.
795
+ #
796
+ def send_datagram data, recipient_address, recipient_port
797
+ data = data.to_s
798
+ EventMachine::send_datagram @signature, data, data.length, recipient_address, recipient_port
799
+ end
800
+
801
+
802
+ end
803
+
804
+
805
+ end # module EventMachine
806
+
Binary file
data/tests/testem.rb ADDED
@@ -0,0 +1,5 @@
1
+ # $Id: testem.rb 2229 2006-04-09 19:03:34Z francis $
2
+ #
3
+ # STUB
4
+ #
5
+
metadata ADDED
@@ -0,0 +1,56 @@
1
+ --- !ruby/object:Gem::Specification
2
+ rubygems_version: 0.8.11
3
+ specification_version: 1
4
+ name: eventmachine-win32
5
+ version: !ruby/object:Gem::Version
6
+ version: 0.5.2
7
+ date: 2006-05-13 00:00:00 -04:00
8
+ summary: Ruby/EventMachine socket engine library- binary gem for Win32
9
+ require_paths:
10
+ - lib
11
+ email: garbagecat10@gmail.com
12
+ homepage: http://rubyeventmachine.com
13
+ rubyforge_project: eventmachine
14
+ description: ""
15
+ autorequire:
16
+ default_executable:
17
+ bindir: bin
18
+ has_rdoc: true
19
+ required_ruby_version: !ruby/object:Gem::Version::Requirement
20
+ requirements:
21
+ - - ">"
22
+ - !ruby/object:Gem::Version
23
+ version: 0.0.0
24
+ version:
25
+ platform: ruby
26
+ signing_key:
27
+ cert_chain:
28
+ authors:
29
+ - Francis Cianfrocca
30
+ files:
31
+ - tests/testem.rb
32
+ - lib/eventmachine.rb
33
+ - lib/rubyeventmachine.so
34
+ - README
35
+ - RELEASE_NOTES
36
+ - COPYING
37
+ test_files:
38
+ - tests/testem.rb
39
+ rdoc_options:
40
+ - --title
41
+ - EventMachine
42
+ - --main
43
+ - README
44
+ - --line-numbers
45
+ extra_rdoc_files:
46
+ - README
47
+ - RELEASE_NOTES
48
+ - COPYING
49
+ executables: []
50
+
51
+ extensions: []
52
+
53
+ requirements: []
54
+
55
+ dependencies: []
56
+