eventmachine 1.0.0.beta.3 → 1.0.0.beta.4

data/lib/em/protocols/httpclient.rb

@@ -3,7 +3,7 @@
 # Author:: Francis Cianfrocca (gmail: blackhedd)
 # Homepage::  http://rubyeventmachine.com
 # Date:: 16 July 2006
-# 
+#
 # See EventMachine and EventMachine::Connection for documentation and
 # usage examples.
 #
@@ -11,25 +11,26 @@
 #
 # 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.
 #
 #---------------------------------------------------------------------------
 #
-# 
+#
 
 
 
 module EventMachine
   module Protocols
 
-    # === Usage
+    # <b>Note:</b> This class is deprecated and will be removed. Please use EM-HTTP-Request instead.
     #
+    # @example
     #  EventMachine.run {
     #    http = EventMachine::Protocols::HttpClient.request(
     #      :host => server,
@@ -62,11 +63,21 @@ module EventMachine
 
       MaxPostContentLength = 20 * 1024 * 1024
 
-      # === Arg list
-      # :host => 'ip/dns', :port => fixnum, :verb => 'GET', :request => 'path',
-      # :basic_auth => {:username => '', :password => ''}, :content => 'content',
-      # :contenttype => 'text/plain', :query_string => '', :host_header => '',
-      # :cookie => ''
+      def initialize
+        warn "HttpClient is deprecated and will be removed. EM-Http-Request should be used instead."
+      end
+
+      # @param args [Hash] The request arguments
+      # @option args [String] :host The host IP/DNS name
+      # @option args [Integer] :port The port to connect too
+      # @option args [String] :verb The request type [GET | POST | DELETE | PUT]
+      # @option args [String] :request The request path
+      # @option args [Hash] :basic_auth The basic auth credentials (:username and :password)
+      # @option args [String] :content The request content
+      # @option args [String] :contenttype The content type (e.g. text/plain)
+      # @option args [String] :query_string The query string
+      # @option args [String] :host_header The host header to set
+      # @option args [String] :cookie Cookies to set
       def self.request( args = {} )
         args[:port] ||= 80
         EventMachine.connect( args[:host], args[:port], self ) {|c|
@@ -265,4 +276,4 @@ module EventMachine
     end
 
   end
-end
+end

data/lib/em/protocols/httpclient2.rb

@@ -26,6 +26,8 @@
 module EventMachine
   module Protocols
 
+    # <b>Note:</b> This class is deprecated and will be removed. Please use EM-HTTP-Request instead.
+    #
     # === Usage
     #
     #  EM.run{
@@ -42,12 +44,15 @@ module EventMachine
       include LineText2
       
       def initialize
+        warn "HttpClient2 is deprecated and will be removed. EM-Http-Request should be used instead."
+
         @authorization = nil
         @closed = nil
         @requests = nil
       end
 
-      class Request # :nodoc:
+      # @private
+      class Request
         include Deferrable
 
         attr_reader :version
@@ -279,12 +284,12 @@ module EventMachine
         request args
       end
 
-      # :stopdoc:
 
       #--
       # Compute and remember a string to be used as the host header in HTTP requests
       # unless the user overrides it with an argument to #request.
       #
+      # @private
       def set_default_host_header host, port, ssl
         if (ssl and port != 443) or (!ssl and port != 80)
           @host_header = "#{host}:#{port}"
@@ -294,11 +299,13 @@ module EventMachine
       end
 
 
+      # @private
       def post_init
         super
         @connected = EM::DefaultDeferrable.new
       end
 
+      # @private
       def connection_completed
         super
         @connected.succeed
@@ -316,12 +323,14 @@ module EventMachine
       # Set and remember a flag (@closed) so we can immediately fail any
       # subsequent requests.
       #
+      # @private
       def unbind
         super
         @closed = true
         (@requests || []).each {|r| r.fail}
       end
 
+      # @private
       def request args
         args[:host_header] = @host_header unless args.has_key?(:host_header)
         args[:authorization] = @authorization unless args.has_key?(:authorization)
@@ -335,6 +344,7 @@ module EventMachine
         r
       end
 
+      # @private
       def receive_line ln
         if req = @requests.last
           req.receive_line ln
@@ -342,8 +352,9 @@ module EventMachine
           p "??????????"
           p ln
         end
-
       end
+
+      # @private
       def receive_binary_data text
         @requests.last.receive_text text
       end
@@ -351,11 +362,10 @@ module EventMachine
       #--
       # Called by a Request object when it completes.
       #
+      # @private
       def pop_request
         @requests.pop
       end
-
-      # :startdoc:
     end
 
 

data/lib/em/protocols/line_protocol.rb

@@ -11,7 +11,8 @@ module EventMachine
     #  end
     #
     module LineProtocol
-      def receive_data data # :nodoc:
+      # @private
+      def receive_data data
         (@buf ||= '') << data
 
         while line = @buf.slice!(/(.*)\r?\n/)

data/lib/em/protocols/memcache.rb

@@ -32,18 +32,23 @@ module EventMachine
       ##
       # constants
 
-      # :stopdoc:
       unless defined? Cempty
+        # @private
         Cstored    = 'STORED'.freeze
+        # @private
         Cend       = 'END'.freeze
+        # @private
         Cdeleted   = 'DELETED'.freeze
+        # @private
         Cunknown   = 'NOT_FOUND'.freeze
+        # @private
         Cerror     = 'ERROR'.freeze
 
+        # @private
         Cempty     = ''.freeze
+        # @private
         Cdelimiter = "\r\n".freeze
       end
-      # :startdoc:
 
       ##
       # commands
@@ -110,9 +115,7 @@ module EventMachine
         EM.connect host, port, self, host, port
       end
 
-      # :stopdoc:
-
-      def send_cmd cmd, key, flags = 0, exptime = 0, bytes = 0, noreply = false # :nodoc:
+      def send_cmd cmd, key, flags = 0, exptime = 0, bytes = 0, noreply = false
         send_data "#{cmd} #{key} #{flags} #{exptime} #{bytes}#{noreply ? ' noreply' : ''}\r\n"
       end
       private :send_cmd
@@ -120,16 +123,19 @@ module EventMachine
       ##
       # errors
 
+      # @private
       class ParserError < StandardError
       end
 
       ##
       # em hooks
 
+      # @private
       def initialize host, port = 11211
         @host, @port = host, port
       end
 
+      # @private
       def connection_completed
         @get_cbs = []
         @set_cbs = []
@@ -148,6 +154,7 @@ module EventMachine
       # 19Feb09 Switched to a custom parser, LineText2 is recursive and can cause
       #         stack overflows when there is too much data.
       # include EM::P::LineText2
+      # @private
       def receive_data data
         (@buffer||='') << data
 
@@ -164,6 +171,7 @@ module EventMachine
 
       #--
       # def receive_line line
+      # @private
       def process_cmd line
         case line.strip
         when /^VALUE\s+(.+?)\s+(\d+)\s+(\d+)/ # VALUE <key> <flags> <bytes>
@@ -209,6 +217,7 @@ module EventMachine
       #   @values[@cur_key] = data[0..-3]
       # end
 
+      # @private
       def unbind
         if @connected or @reconnecting
           EM.add_timer(1){ reconnect @host, @port }
@@ -219,8 +228,6 @@ module EventMachine
           raise 'Unable to connect to memcached server'
         end
       end
-
-      # :startdoc:
     end
   end
 end
@@ -229,7 +236,8 @@ if __FILE__ == $0
   # ruby -I ext:lib -r eventmachine -rubygems lib/protocols/memcache.rb
   require 'em/spec'
 
-  class TestConnection # :nodoc:
+  # @private
+  class TestConnection
     include EM::P::Memcache
     def send_data data
       sent_data << data
@@ -320,4 +328,4 @@ if __FILE__ == $0
     end
 
   end
-end
+end

data/lib/em/protocols/object_protocol.rb

@@ -17,7 +17,8 @@ module EventMachine
         Marshal
       end
 
-      def receive_data data # :nodoc:
+      # @private
+      def receive_data data
         (@buf ||= '') << data
 
         while @buf.size >= 4

data/lib/em/protocols/postgres3.rb

@@ -24,25 +24,24 @@
 # 
 # 
 
-require 'readbytes'
 require 'postgres-pr/message'
 require 'postgres-pr/connection'
 require 'stringio'
 
-class StringIO # :nodoc:
+# @private
+class StringIO
   # Reads exactly +n+ bytes.
   #
   # If the data read is nil an EOFError is raised.
   #
-  # If the data read is too short a TruncatedDataError is raised and the read
-  # data is obtainable via its #data method.
+  # If the data read is too short an IOError is raised
   def readbytes(n)
     str = read(n)
     if str == nil
       raise EOFError, "End of file reached"
     end
     if str.size < n
-      raise TruncatedDataError.new("data truncated", str) 
+      raise IOError, "data truncated"
     end
     str
   end
@@ -67,15 +66,15 @@ module EventMachine
     # in basically a production-ready state, and the wire protocol isn't that complicated
     # anyway.
     #
-    # We need to monkeypatch StringIO because it lacks the #readbytes method needed
-    # by postgres-pr.
-    #
     # We're tucking in a bunch of require statements that may not be present in garden-variety
     # EM installations. Until we find a good way to only require these if a program
     # requires postgres, this file will need to be required explicitly.
     #
-    # The StringIO monkeypatch is lifted verbatim from the standard library readbytes.rb,
+    # We need to monkeypatch StringIO because it lacks the #readbytes method needed
+    # by postgres-pr.
+    # The StringIO monkeypatch is lifted from the standard library readbytes.rb,
     # which adds method #readbytes directly to class IO. But StringIO is not a subclass of IO.
+    # It is modified to raise an IOError instead of TruncatedDataException since the exception is unused.
     #
     # We cloned the handling of postgres messages from lib/postgres-pr/connection.rb
     # in the postgres-pr library, and modified it for event-handling.

data/lib/em/protocols/smtpclient.rb

@@ -3,7 +3,7 @@
 # Author:: Francis Cianfrocca (gmail: blackhedd)
 # Homepage::  http://rubyeventmachine.com
 # Date:: 16 July 2006
-# 
+#
 # See EventMachine and EventMachine::Connection for documentation and
 # usage examples.
 #
@@ -11,17 +11,17 @@
 #
 # 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.
 #
 #---------------------------------------------------------------------------
 #
-# 
+#
 
 require 'ostruct'
 
@@ -30,6 +30,7 @@ module EventMachine
 
     # Simple SMTP client
     #
+    # @example
     #  email = EM::Protocols::SmtpClient.send(
     #    :domain=>"example.com",
     #    :host=>'localhost',
@@ -66,7 +67,7 @@ module EventMachine
     class SmtpClient < Connection
       include EventMachine::Deferrable
       include EventMachine::Protocols::LineText2
-      
+
       def initialize
         @succeeded = nil
         @responder = nil
@@ -91,7 +92,10 @@ module EventMachine
       #   depending on the type.
       #   Currently only :type => :plain is supported. Pass additional parameters :username (String),
       #   and :password (either a String or a Proc that will be called at auth-time).
-      #   Example: :auth => {:type=>:plain, :username=>"mickey@disney.com", :password=>"mouse"}
+      #
+      #   @example
+      #     :auth => {:type=>:plain, :username=>"mickey@disney.com", :password=>"mouse"}
+      #
       # :from => required String
       #   Specifies the sender of the message. Will be passed as the argument
       #   to the MAIL FROM. Do NOT enclose the argument in angle-bracket (<>) characters.
@@ -109,7 +113,9 @@ module EventMachine
       #   containing the header values. TODO, support Arrays of header values, which would cause us to
       #   send that specific header line more than once.
       #
-      #   Example: :header => {"Subject" => "Bogus", "CC" => "myboss@example.com"}
+      #   @example
+      #     :header => {"Subject" => "Bogus", "CC" => "myboss@example.com"}
+      #
       # :body => Optional string, defaults blank.
       #   This will be passed as the body of the email message.
       #   TODO, this needs to be significantly beefed up. As currently written, this requires the caller
@@ -156,15 +162,15 @@ module EventMachine
         }
       end
 
-      # :stopdoc:
-
       attr_writer :args
 
+      # @private
       def post_init
         @return_values = OpenStruct.new
         @return_values.start_time = Time.now
       end
 
+      # @private
       def connection_completed
         @responder = :receive_signon
         @msg = []
@@ -175,6 +181,7 @@ module EventMachine
       # set a deferred success because the caller will already have done it
       # (no need to wait until the connection closes to invoke the callbacks).
       #
+      # @private
       def unbind
         unless @succeeded
           @return_values.elapsed_time = Time.now - @return_values.start_time
@@ -185,6 +192,7 @@ module EventMachine
         end
       end
 
+      # @private
       def receive_line ln
         $>.puts ln if @args[:verbose]
         @range = ln[0...1].to_i
@@ -197,6 +205,8 @@ module EventMachine
         end
       end
 
+      private
+
       # We encountered an error from the server and will close the connection.
       # Use the error and message the server returned.
       #
@@ -350,8 +360,6 @@ module EventMachine
         @return_values.message = @msg
         set_deferred_status :succeeded, @return_values
       end
-
-      # :startdoc:
     end
   end
 end