"asyncore" — 非同期ソケットハンドラ
***********************************

**ソースコード:** Lib/asyncore.py

======================================================================

このモジュールは、非同期ソケットサービスのクライアント・サーバを開発す
るための基盤として使われます。

CPUが一つしかない場合、プログラムが」二つのことを同時に」実行する方法
は二つしかありません。もっとも簡単で一般的なのはマルチスレッドを利用す
る方法ですが、これとはまったく異なるテクニックで、一つのスレッドだけで
マルチスレッドと同じような効果を得られるテクニックがあります。このテク
ニックはI/O処理が中心である場合にのみ有効で、CPU負荷の高いプログラムで
は効果が無く、この場合にはプリエンプティブなスケジューリングが可能なス
レッドが有効でしょう。しかし、多くの場合、ネットワークサーバではCPU負
荷よりはIO負荷が問題となります。

もしOSのI/Oライブラリがシステムコール "select()" をサポートしている場
合（ほとんどの場合はサポートされている）、I/O処理は」バックグラウンド
」で実行し、その間に他の処理を実行すれば、複数の通信チャネルを同時にこ
なすことができます。一見、この戦略は奇妙で複雑に思えるかもしれませんが
、いろいろな面でマルチスレッドよりも理解しやすく、制御も容易です。
"asyncore" は多くの複雑な問題を解決済みなので、洗練され、パフォーマン
スにも優れたネットワークサーバとクライアントを簡単に開発することができ
ます。とくに、 "asynchat" のような、対話型のアプリケーションやプロトコ
ルには非常に有効でしょう。

基本的には、この二つのモジュールを使う場合は一つ以上のネットワーク *チ
ャネル* を "asyncore.dispatcher" クラス、または "asynchat.async_chat"
のインスタンスとして作成します。作成されたチャネルはグローバルマップに
登録され、 "loop()" 関数で参照されます。 "loop()" には、専用の *マップ
* を渡す事も可能です。

チャネルを生成後、 "loop()" を呼び出すとチャネル処理が開始し、最後のチ
ャネル（非同期処理中にマップに追加されたチャネルを含む）が閉じるまで継
続します。

asyncore.loop([timeout[, use_poll[, map[, count]]]])

   ポーリングループを開始し、count 回が過ぎるか、全てのオープン済みチ
   ャネルがクローズされた場合のみ終了します。全ての引数はオプションで
   す。引数 *count* のデフォルト値は "None" で、ループは全てのチャネル
   がクローズされた場合のみ終了します。引数 *timeout* は "select()" ま
   たは "poll()" の引数 timeout として渡され、秒単位で指定します。デフ
   ォルト値は 30 秒です。引数 *use_poll* が真の場合、 "select()" では
   なく "poll()" が使われます (デフォルト値は "False" です)。

   引数 *map* には、監視するチャネルをアイテムとして格納した辞書を指定
   します。チャネルがクローズされた時に *map* からそのチャネルが削除さ
   れます。 *map* が省略された場合、グローバルなマップが使用されます。
   チャネル ("asyncore.dispatcher", "asynchat.async_chat" とそのサブク
   ラス) は自由に混ぜて map に入れることができます。

class asyncore.dispatcher

   "dispatcher" クラスは、低レベルソケットオブジェクトの薄いラッパーで
   す。便宜上、非同期ループから呼び出されるイベント処理メソッドを追加
   していますが、これ以外の点では、non-blockingなソケットと同様です。

   非同期ループ内で低レベルイベントが発生した場合、発生のタイミングや
   コネクションの状態から特定の高レベルイベントへと置き換えることがで
   きます。例えばソケットを他のホストに接続する場合、最初の書き込み可
   能イベントが発生すれば接続が完了した事が分かります(この時点で、ソケ
   ットへの書き込みは成功すると考えられる)。このように判定できる高レベ
   ルイベントを以下に示します:

   +------------------------+------------------------------------------+
   | Event                  | 説明                                     |
   +========================+==========================================+
   | "handle_connect()"     | 最初にreadもしくはwriteイベントが発生し  |
   |                        | た時                                     |
   +------------------------+------------------------------------------+
   | "handle_close()"       | 読み込み可能なデータなしでreadイベントが |
   |                        | 発生した時                               |
   +------------------------+------------------------------------------+
   | "handle_accept()"      | listen中のソケットでreadイベントが発生し |
   |                        | た時                                     |
   +------------------------+------------------------------------------+

   非同期処理中、マップに登録されたチャネルの "readable()" メソッドと
   "writable()" メソッドが呼び出され、 "select()" か "poll()" で
   read/writeイベントを検出するリストに登録するか否かを判定します。

   このようにして、チャネルでは低レベルなソケットイベントの種類より多
   くの種類のイベントを検出する事ができます。以下にあげるイベントは、
   サブクラスでオーバライドすることが可能です:

   handle_read()

      非同期ループで、チャネルのソケットの "read()" メソッドの呼び出し
      が成功した時に呼び出されます。

   handle_write()

      非同期ループで、書き込み可能ソケットが実際に書き込み可能になった
      時に呼び出されます。このメソッドでは、しばしばパフォーマンスの向
      上のために必要なバッファリングを実装します。例:

         def handle_write(self):
             sent = self.send(self.buffer)
             self.buffer = self.buffer[sent:]

   handle_expt()

      out of band (OOB)データが検出された時に呼び出されます。OOBはあま
      りサポートされておらず、また滅多に使われないので、
      "handle_expt()" が呼び出されることはほとんどありません。

   handle_connect()

      ソケットの接続が確立した時に呼び出されます。」welcome」バナーの
      送信、プロトコルネゴシエーションの初期化などを行います。

   handle_close()

      ソケットが閉じた時に呼び出されます。

   handle_error()

      捕捉されない例外が発生した時に呼び出されます。デフォルトでは、短
      縮したトレースバック情報が出力されます。

   handle_accept()

      Called on listening channels (passive openers) when a connection
      can be established with a new remote endpoint that has issued a
      "connect()" call for the local endpoint.

   readable()

      非同期ループ中に呼び出され、readイベントの監視リストに加えるか否
      かを決定します。デフォルトのメソッドでは "True" を返し、readイベ
      ントの発生を監視します。

   writable()

      非同期ループ中に呼び出され、writeイベントの監視リストに加えるか
      否かを決定します。デフォルトのメソッドでは "True" を返し、write
      イベントの発生を監視します。

   さらに、チャネルにはソケットのメソッドとほぼ同じメソッドがあり、チ
   ャネルはソケットのメソッドの多くを委譲・拡張しており、ソケットとほ
   ぼ同じメソッドを持っています。

   create_socket(family, type)

      引数も含め、通常のソケット生成と同一です。ソケットの生成について
      は、 "socket" モジュールのドキュメントを参照してください。

   connect(address)

      通常のソケットオブジェクトと同様、*address* には一番目の値が接続
      先ホスト、2番目の値がポート番号であるタプルを指定します。

   send(data)

      リモート側の端点に *data* を送出します。

   recv(buffer_size)

      Read at most *buffer_size* bytes from the socket’s remote end-
      point.  An empty string implies that the channel has been closed
      from the other end.

      Note that "recv()" may raise "socket.error" with "EAGAIN" or
      "EWOULDBLOCK", even though "select.select()" or "select.poll()"
      has reported the socket ready for reading.

   listen(backlog)

      ソケットへの接続を待ちます。引数 *backlog* は、キューに追加でき
      るコネクションの最大数 (1 以上) を指定します。最大値はシステムに
      依存します（通常は5)。

   bind(address)

      ソケットを *address* にバインドします。ソケットはバインド済みで
      あってはなりません。 (*address* の形式は、アドレスファミリに依存
      します。 "socket" モジュールを参照のこと。) ソケットを再利用可能
      にする ("SO_REUSEADDR" オプションを設定する) には、 "dispatcher"
      オブジェクトの "set_reuse_addr()" メソッドを呼び出してください。

   accept()

      接続を受け入れます。ソケットはアドレスにバインド済みであり、
      "listen()" で接続待ち状態でなければなりません。戻り値は "None"
      か "(conn, address)" のペアで、*conn* はデータの送受信を行う **
      新しい** ソケットオブジェクト、*address* は接続先ソケットがバイ
      ンドされているアドレスです。"None" が返された場合、接続が起こら
      なかったことを意味します。その場合、サーバーはこのイベントを無視
      して後続の接続を待ち続けるべきです。

   close()

      ソケットをクローズします。以降の全ての操作は失敗します。リモート
      端点では、キューに溜まったデータ以外、これ以降のデータ受信は行え
      ません。ソケットはガベージコレクト時に自動的にクローズされます。

class asyncore.dispatcher_with_send

   "dispatcher" のサブクラスで、シンプルなバッファされた出力機能を持ち
   ます。シンプルなクライアントプログラムに適しています。もっと高レベ
   ルな場合には "asynchat.async_chat" を利用してください。

class asyncore.file_dispatcher

   A file_dispatcher takes a file descriptor or file object along with
   an optional map argument and wraps it for use with the "poll()" or
   "loop()" functions.  If provided a file object or anything with a
   "fileno()" method, that method will be called and passed to the
   "file_wrapper" constructor.  Availability: UNIX.

class asyncore.file_wrapper

   file_wrapper は整数のファイルデスクリプタを受け取って "os.dup()" を
   呼び出してハンドルを複製するので、元のハンドルは file_wrapper と独
   立してclose されます。このクラスは "file_dispatcher" クラスが使うた
   めに必要なソケットをエミュレートするメソッドを実装しています。利用
   できるプラットフォーム: UNIX。


asyncoreの例: 簡単なHTTPクライアント
====================================

基本的なサンプルとして、以下に非常に単純なHTTPクライアントを示します。
このHTTPクライアントは "dispatcher" クラスでソケットを利用しています:

   import asyncore, socket

   class HTTPClient(asyncore.dispatcher):

       def __init__(self, host, path):
           asyncore.dispatcher.__init__(self)
           self.create_socket(socket.AF_INET, socket.SOCK_STREAM)
           self.connect( (host, 80) )
           self.buffer = 'GET %s HTTP/1.0\r\n\r\n' % path

       def handle_connect(self):
           pass

       def handle_close(self):
           self.close()

       def handle_read(self):
           print self.recv(8192)

       def writable(self):
           return (len(self.buffer) > 0)

       def handle_write(self):
           sent = self.send(self.buffer)
           self.buffer = self.buffer[sent:]


   client = HTTPClient('www.python.org', '/')
   asyncore.loop()


基本的な echo サーバーの例
==========================

この例の基本的な echoサーバーは、 "dispatcher" を利用して接続を受けつ
け、接続をハンドラーにディスパッチします:

   import asyncore
   import socket

   class EchoHandler(asyncore.dispatcher_with_send):

       def handle_read(self):
           data = self.recv(8192)
           if data:
               self.send(data)

   class EchoServer(asyncore.dispatcher):

       def __init__(self, host, port):
           asyncore.dispatcher.__init__(self)
           self.create_socket(socket.AF_INET, socket.SOCK_STREAM)
           self.set_reuse_addr()
           self.bind((host, port))
           self.listen(5)

       def handle_accept(self):
           pair = self.accept()
           if pair is not None:
               sock, addr = pair
               print 'Incoming connection from %s' % repr(addr)
               handler = EchoHandler(sock)

   server = EchoServer('localhost', 8080)
   asyncore.loop()
