comments

Workerman/Connection/AsyncTcpConnection.php

@@ -8,33 +8,35 @@ use Workerman\Worker;
 use \Exception;
 
 /**
- * async connection 
+ * 异步tcp连接类 
  * @author walkor<walkor@workerman.net>
  */
 class AsyncTcpConnection extends TcpConnection
 {
     /**
-     * status
+     * 连接状态 连接中
      * @var int
      */
     protected $_status = self::STATUS_CONNECTING;
     
     /**
-     * when connect success , onConnect will be run
+     * 当连接成功时，如果设置了连接成功回调，则执行
      * @var callback
      */
     public $onConnect = null;
     
     /**
-     * create a connection
+     * 构造函数，创建连接
      * @param resource $socket
      * @param EventInterface $event
      */
     public function __construct($remote_address)
     {
+        // 获得协议及远程地址
         list($scheme, $address) = explode(':', $remote_address, 2);
         if($scheme != 'tcp')
         {
+            // 判断协议类是否存在
             $scheme = ucfirst($scheme);
             $this->protocol = '\\Protocols\\'.$scheme;
             if(!class_exists($this->protocol))
@@ -46,16 +48,24 @@ class AsyncTcpConnection extends TcpConnection
                 }
             }
         }
+        // 创建异步连接
         $this->_socket = stream_socket_client("tcp:$address", $errno, $errstr, 0, STREAM_CLIENT_ASYNC_CONNECT);
+        // 如果失败尝试触发失败回调（如果有回调的话）
         if(!$this->_socket)
         {
             $this->emitError(WORKERMAN_CONNECT_FAIL, $errstr);
             return;
         }
-        
+        // 监听连接可写事件（可写意味着连接已经建立或者已经出错）
         Worker::$globalEvent->add($this->_socket, EventInterface::EV_WRITE, array($this, 'checkConnection'));
     }
     
+    /**
+     * 尝试触发失败回调
+     * @param int $code
+     * @param string $msg
+     * @return void
+     */
     protected function emitError($code, $msg)
     {
         if($this->onError)
@@ -70,20 +80,32 @@ class AsyncTcpConnection extends TcpConnection
         }
     }
     
+    /**
+     * 检查连接状态，连接成功还是失败
+     * @param resource $socket
+     * @return void
+     */
     public function checkConnection($socket)
     {
+        // 删除连接可写监听
         Worker::$globalEvent->del($this->_socket, EventInterface::EV_WRITE);
-        // php bug ?
+        // 需要判断两次连接是否已经断开
         if(!feof($this->_socket) && !feof($this->_socket))
         {
+            // 设置非阻塞
             stream_set_blocking($this->_socket, 0);
+            // 监听可读事件
             Worker::$globalEvent->add($this->_socket, EventInterface::EV_READ, array($this, 'baseRead'));
+            // 如果发送缓冲区有数据则执行发送
             if($this->_sendBuffer)
             {
                 Worker::$globalEvent->add($this->_socket, EventInterface::EV_WRITE, array($this, 'baseWrite'));
             }
+            // 标记状态为连接已经建立
             $this->_status = self::STATUS_ESTABLISH;
+            // 为status 命令统计数据
             ConnectionInterface::$statistics['connection_count']++;
+            // 如果有设置onConnect回调，则执行
             if($this->onConnect)
             {
                 try 
@@ -99,63 +121,76 @@ class AsyncTcpConnection extends TcpConnection
         }
         else
         {
-            $this->emitError(WORKERMAN_CONNECT_FAIL, 'connect fail, maybe timedout');
+            // 连接未建立成功
+            $this->emitError(WORKERMAN_CONNECT_FAIL, 'connect fail');
         }
     }
     
     /**
-     * send buffer to client
+     * 发送数据给对方
      * @param string $send_buffer
      * @return void|boolean
      */
     public function send($send_buffer)
     {
+        // 如果有设置协议，则用协议编码
         if($this->protocol)
         {
             $parser = $this->protocol;
             $send_buffer = $parser::encode($send_buffer, $this);
         }
         
+        // 如果当前状态是连接中，则把数据放入发送缓冲区
         if($this->_status === self::STATUS_CONNECTING)
         {
             $this->_sendBuffer .= $send_buffer;
             return null;
         }
+        // 如果当前连接是关闭中，则返回false
         elseif($this->_status == self::STATUS_CLOSED)
         {
             return false;
         }
-        
+        // 如果发送缓冲区无数据，则尝试直接发送
         if($this->_sendBuffer === '')
         {
+            // 直接发送，得到已经发送（写入socket写缓冲区）的字节数
             $len = @fwrite($this->_socket, $send_buffer);
+            // 如果已经发送出去的长度刚好为要发送数据的长度，则说明数据发送成功
             if($len === strlen($send_buffer))
             {
                 return true;
             }
-            
+            // 数据只发送了一部分，则将剩余的数据放入发送缓冲区
             if($len > 0)
             {
                 $this->_sendBuffer = substr($send_buffer, $len);
             }
+            // 发送出现异常
             else
             {
+                // 如果连接关闭
                 if(feof($this->_socket))
                 {
+                    // status命令 统计发送失败次数
                     self::$statistics['send_fail']++;
+                    // 如果有设置失败回到，则执行
                     if($this->onError)
                     {
                         call_user_func($this->onError, $this, WORKERMAN_SEND_FAIL, 'client close');
                     }
+                    // 销毁本实例
                     $this->destroy();
                     return false;
                 }
+                // 连接未关闭，则将整个数据放入发送缓冲区
                 $this->_sendBuffer = $send_buffer;
             }
-            
+            // 监听可写事件，将发送缓冲区的数据发送给对方（写到socket发送缓冲区）
             Worker::$globalEvent->add($this->_socket, EventInterface::EV_WRITE, array($this, 'baseWrite'));
             return null;
         }
+        // 发送缓冲区有数据，则直接将数据放入发送缓冲区
         else
         {
             $this->_sendBuffer .= $send_buffer;

Workerman/Connection/ConnectionInterface.php

@@ -7,13 +7,13 @@ use Workerman\Worker;
 use \Exception;
 
 /**
- * connection 
+ * connection类的接口 
  * @author walkor<walkor@workerman.net>
  */
 abstract class  ConnectionInterface
 {
     /**
-     * statistics for status
+     * status命令的统计数据
      * @var array
      */
     public static $statistics = array(
@@ -24,43 +24,44 @@ abstract class  ConnectionInterface
     );
     
     /**
-     * when receive data, onMessage will be run 
+     * 当收到数据时，如果有设置$onMessage回调，则执行
      * @var callback
      */
     public $onMessage = null;
     
     /**
-     * when connection close, onClose will be run
+     * 当连接关闭时，如果设置了$onClose回调，则执行
      * @var callback
      */
     public $onClose = null;
     
     /**
-     * when something wrong ,onError will be run
+     * 当出现错误时，如果设置了$onError回调，则执行
      * @var callback
      */
     public $onError = null;
     
     /**
-     * send buffer to client
+     * 发送数据给对端
      * @param string $send_buffer
      * @return void|boolean
      */
     abstract public function send($send_buffer);
     
     /**
-     * get remote ip
+     * 获得远端ip
      * @return string
      */
     abstract public function getRemoteIp();
     
     /**
-     * get remote port
+     * 获得远端端口
+     * @return int
      */
     abstract public function getRemotePort();
 
     /**
-     * close the connection
+     * 关闭连接，为了保持接口一致，udp保留了此方法，当是udp时调用此方法无任何作用
      * @void
      */
     abstract public function close($data = null);

Workerman/Connection/TcpConnection.php

@@ -8,127 +8,136 @@ use Workerman\Worker;
 use \Exception;
 
 /**
- * connection 
+ * Tcp连接类 
  * @author walkor<walkor@workerman.net>
  */
 class TcpConnection extends ConnectionInterface
 {
     /**
-     * when recv data from client ,how much bytes to read
-     * @var unknown_type
+     * 当数据可读时，从socket缓冲区读取多少字节数据
+     * @var int
      */
     const READ_BUFFER_SIZE = 8192;
 
     /**
-     * connection status connecting
+     * 连接状态 连接中
      * @var int
      */
     const STATUS_CONNECTING = 1;
     
     /**
-     * connection status establish
+     * 连接状态 已经建立连接
      * @var int
      */
     const STATUS_ESTABLISH = 2;
 
     /**
-     * connection status closing
+     * 连接状态 连接关闭中，标识调用了close方法，但是发送缓冲区中任然有数据
+     * 等待发送缓冲区的数据发送完毕（写入到socket写缓冲区）后执行关闭
      * @var int
      */
     const STATUS_CLOSING = 4;
     
     /**
-     * connection status closed
+     * 连接状态 已经关闭
      * @var int
      */
     const STATUS_CLOSED = 8;
     
     /**
-     * when receive data, onMessage will be run 
+     * 当对端发来数据时，如果设置了$onMessage回调，则执行
      * @var callback
      */
     public $onMessage = null;
     
     /**
-     * when connection close, onClose will be run
+     * 当连接关闭时，如果设置了$onClose回调，则执行
      * @var callback
      */
     public $onClose = null;
     
     /**
-     * when some thing wrong ,onError will be run
+     * 当出现错误是，如果设置了$onError回调，则执行
      * @var callback
      */
     public $onError = null;
     
     /**
-     * protocol
+     * 使用的应用层协议，是协议类的名称
+     * 值类似于 Workerman\\Protocols\\Http
      * @var string
      */
     public $protocol = '';
     
     /**
-     * max send buffer size (Bytes)
+     * 发送缓冲区大小，当发送缓冲区满时，会尝试触发onError回调（如果有设置的话）
+     * 如果没设置onError回调，发送缓冲区满，则后续发送的数据将被丢弃，
+     * 直到发送缓冲区有空的位置
+     * 注意 此值可以动态设置
+     * 例如 Workerman\Connection\TcpConnection::$maxSendBufferSize=1024000;
      * @var int
      */
     public static $maxSendBufferSize = 1048576;
     
     /**
-     * max package size (Bytes)
+     * 能接受的最大数据包，为了防止恶意攻击，当数据包的大小大于此值时执行断开
+     * 注意 此值可以动态设置
+     * 例如 Workerman\Connection\TcpConnection::$maxPackageSize=1024000;
      * @var int
      */
     public static $maxPackageSize = 10485760;
     
     /**
-     * the socket
+     * 实际的socket资源
      * @var resource
      */
     protected $_socket = null;
 
     /**
-     * the buffer to send
+     * 发送缓冲区
      * @var string
      */
     protected $_sendBuffer = '';
     
     /**
-     * the buffer read from socket
+     * 接收缓冲区
      * @var string
      */
     protected $_recvBuffer = '';
     
     /**
-     * current package length
+     * 当前正在处理的数据包的包长（此值是协议的intput方法的返回值）
      * @var int
      */
     protected $_currentPackageLength = 0;
 
     /**
-     * connection status
+     * 当前的连接状态
      * @var int
      */
     protected $_status = self::STATUS_ESTABLISH;
     
     /**
-     * remote ip
+     * 对端ip
      * @var string
      */
     protected $_remoteIp = '';
     
     /**
-     * remote port
+     * 对端端口
      * @var int
      */
     protected $_remotePort = 0;
     
     /**
-     * remote address
+     * 对端的地址 ip+port
+     * 值类似于 192.168.1.100:3698
      * @var string
      */
     protected $_remoteAddress = '';
 
     /**
-     * create a connection
+     * 构造函数
      * @param resource $socket
      * @param EventInterface $event
      */
@@ -140,65 +149,78 @@ class TcpConnection extends ConnectionInterface
     }
     
     /**
-     * send buffer to client
+     * 发送数据给对端
      * @param string $send_buffer
      * @param bool $raw
      * @return void|boolean
      */
     public function send($send_buffer, $raw = false)
     {
+        // 如果连接已经关闭，则返回false
         if($this->_status == self::STATUS_CLOSED)
         {
             return false;
         }
+        // 如果没有设置以原始数据发送，并且有设置协议。只协议编码
         if(false === $raw && $this->protocol)
         {
             $parser = $this->protocol;
             $send_buffer = $parser::encode($send_buffer, $this);
         }
-        
+        // 如果发送缓冲区为空，尝试直接发送
         if($this->_sendBuffer === '')
         {
+            // 直接发送
             $len = @fwrite($this->_socket, $send_buffer);
+            // 所有数据都发送完毕
             if($len === strlen($send_buffer))
             {
                 return true;
             }
-            
+            // 只有部分数据发送成功
             if($len > 0)
             {
+                // 未发送成功部分放入发送缓冲区
                 $this->_sendBuffer = substr($send_buffer, $len);
             }
             else
             {
+                // 如果连接断开
                 if(feof($this->_socket))
                 {
+                    // status统计发送失败次数
                     self::$statistics['send_fail']++;
+                    // 如果有设置失败回调，则执行
                     if($this->onError)
                     {
                         call_user_func($this->onError, $this, WORKERMAN_SEND_FAIL, 'client closed');
                     }
+                    // 销毁连接
                     $this->destroy();
                     return false;
                 }
+                // 连接未断开，发送失败，则把所有数据放入发送缓冲区
                 $this->_sendBuffer = $send_buffer;
             }
-            
+            // 监听对端可写事件
             Worker::$globalEvent->add($this->_socket, EventInterface::EV_WRITE, array($this, 'baseWrite'));
             return null;
         }
         else
         {
-            // check send buffer size
+            // 检查发送缓冲区是否已满
             if(self::$maxSendBufferSize <= strlen($this->_sendBuffer) + strlen($send_buffer))
             {
+                // 为status命令统计发送失败次数
                 self::$statistics['send_fail']++;
+                // 如果有设置失败回调，则执行
                 if($this->onError)
                 {
                     call_user_func($this->onError, $this, WORKERMAN_SEND_FAIL, 'send buffer full');
                 }
                 return false;
             }
+            // 将数据放入放缓冲区
             $this->_sendBuffer .= $send_buffer;
         }
     }

Workerman/Connection/UdpConnection.php

@@ -8,43 +8,45 @@ use Workerman\Worker;
 use \Exception;
 
 /**
- * connection 
+ * udp连接类（udp实际上是无连接的，这里是为了保持与TCP接口一致） 
  * @author walkor<walkor@workerman.net>
  */
 class UdpConnection extends ConnectionInterface
 {
     /**
-     * protocol
+     * 应用层协议
+     * 值类似于 Workerman\\Protocols\\Http
      * @var string
      */
     public $protocol = '';
     
     /**
-     * the socket
+     * udp socket 资源
      * @var resource
      */
     protected $_socket = null;
     
     /**
-     * remote ip
+     * 对端 ip
      * @var string
      */
     protected $_remoteIp = '';
     
     /**
-     * remote port
+     * 对端 端口
      * @var int
      */
     protected $_remotePort = 0;
     
     /**
-     * remote address
+     * 对端 地址
+     * 值类似于 192.168.10.100:3698
      * @var string
      */
     protected $_remoteAddress = '';
 
     /**
-     * create a connection
+     * 构造函数
      * @param resource $socket
      * @param string $remote_address
      */
@@ -55,7 +57,7 @@ class UdpConnection extends ConnectionInterface
     }
     
     /**
-     * send buffer to client
+     * 发送数据给对端
      * @param string $send_buffer
      * @return void|boolean
      */
@@ -65,7 +67,7 @@ class UdpConnection extends ConnectionInterface
     }
     
     /**
-     * get remote ip
+     * 获得对端 ip
      * @return string
      */
     public function getRemoteIp()
@@ -78,7 +80,7 @@ class UdpConnection extends ConnectionInterface
     }
     
     /**
-     * get remote port
+     * 获得对端端口
      */
     public function getRemotePort()
     {
@@ -90,7 +92,7 @@ class UdpConnection extends ConnectionInterface
     }
 
     /**
-     * close the connection
+     * 关闭连接（此处为了保持与TCP接口一致，提供了close方法）
      * @void
      */
     public function close($data = null)