ext-uv/README.md

# php-uv

[![Build Status](https://secure.travis-ci.org/chobie/php-uv.png)](http://travis-ci.org/chobie/php-uv)

interface to libuv for php (experimental). also supports http-parser.

# Experimental

This extension is experimental, its functions may change their names 
or move to extension all together so do not rely to much on them you have been warned!

# Install

````
git clone https://github.com/chobie/php-uv.git --recursive
cd php-uv
(cd libuv && make)
phpize
./configure
make
make install
# add `extension=uv.so` to your php.ini
````

# Examples

see examples and tests directory.

````
<?php
$tcp = uv_tcp_init();

uv_tcp_bind($tcp, uv_ip4_addr('0.0.0.0',8888));

uv_listen($tcp,100, function($server){
    $client = uv_tcp_init();
    uv_accept($server, $client);
    var_dump(uv_tcp_getsockname($server));

    uv_read_start($client, function($socket, $nread, $buffer){
        var_dump($buffer);
        uv_close($socket);
    });
});

$c = uv_tcp_init();
uv_tcp_connect($c, uv_ip4_addr('0.0.0.0',8888), function($stream, $stat){
    if ($stat == 0) {
        uv_write($stream,"Hello",function($stream, $stat){
            uv_close($stream);
        });
    }
});

uv_run();
````

# Community

Check out #php-uv on irc.freenode.net.

# Author

* Shuhei Tanuma

# License

PHP License


# Documents

this documents was generated by `examples/docgen.php`.

### void uv_unref(resource $uv_t)


### long uv_last_error([resource $uv_loop])


### string uv_err_name(long $error_code)


### string uv_strerror(long $error_code)


### void uv_update_time(resource $uv_loop)


### void uv_ref(resource $uv_handle)


### void uv_run([resource $uv_loop])


### void uv_run_once([resource $uv_loop])


### void uv_loop_delete(resource $uv_loop)


### long uv_now(resource $uv_loop)


### void uv_tcp_bind(resource $uv_sockaddr)


### void uv_tcp_bind6(resource $uv_sockaddr)


### void uv_write(resource $handle, string $data, callable $callback)

##### *Description*

send buffer to speicified uv resource.

##### *Parameters*

*resource $handle*: uv resources (uv_tcp, uv_udp, uv_pipe ...etc.)
*string $data*: buffer.
*callable $callback*: callable variables. this callback expects (resource $handle, long $status)

##### *Return Value*

*void*: 

##### *Example*



### void uv_write2(resource $handle, string $data, resource $send, callable $callback)


### void uv_tcp_nodelay(resource $handle, bool $flag)


### void uv_accept(resource $server, resource $client)


### void uv_shutdown(resource $handle, callable $callback)

##### *Description*

shutdown uv handle.

##### *Parameters*

*resource $handle*: uv resources (uv_tcp, uv_udp, uv_pipe ...etc.)
*callable $callback*: callable variables. this callback expects (resource $handle, long $status)

##### *Return Value*

*void*: 

##### *Example*



### void uv_close(resource $handle, callable $callback)

##### *Description*

close uv handle.

##### *Parameters*

*resource $handle*: uv resources (uv_tcp, uv_udp, uv_pipe ...etc.)
*callable $callback*: callable variables. this callback expects (resource $handle, long $status)

##### *Return Value*

*void*: 

##### *Example*



### void uv_read_start(resource $handle, callable $callback)

##### *Description*

starts read callback for uv resources.

##### *Parameters*

*resource $handle*: uv resources (uv_tcp, uv_udp, uv_pipe ...etc.)
*callable $callback*: callable variables. this callback parameter expects (resource $handle, long $nread, string buffer)

##### *Return Value*

*void*: 

##### *Example*

##### *Note*

* You have to handle erorrs correctly. otherwise this will leak.
* if you want to use PHP's stream or socket resource. see uv_fs_poll_init and uv_fs_read.



### void uv_read2_start(resource $handle, callable $callback)


### void uv_read_stop(resource $handle)


### resource uv_ip4_addr(string $ipv4_addr, long $port)


### resource uv_ip6_addr(string $ipv6_addr, long $port)


### void uv_listen(resource $handle, long $backlog, callable $callback)


### void uv_tcp_connect(resource $handle, resource $ipv4_addr, callable $callback)

##### *Description*

connect to specified ip address and port.

##### *Parameters*

*resource $handle*: requires `uv_tcp_init()` resource.
*resource $ipv4_addr*: requires uv_sockaddr resource.
*callable $callback*: callable variables.

##### *Return Value*

*void*: 

##### *Example*

````php
<?php
$tcp = uv_tcp_init();
uv_tcp_connect($tcp, uv_ip4_addr("127.0.0.1",8080), function($tcp_handle, $status){
	uv_close($tcp_handle);
});

uv_run();
````


### void uv_tcp_connect6(resource $handle, resource $ipv6_addr, callable $callback)

##### *Description*

connect to specified ip address and port.

##### *Parameters*

*resource $handle*: requires `uv_tcp_init()` resource.
*resource $ipv4_addr*: requires uv_sockaddr resource.
*callable $callback*: callable variables.

##### *Return Value*

*void*: 

##### *Example*

````php
<?php
$tcp = uv_tcp_init();
uv_tcp_connect($tcp, uv_ip6_addr("::1",8080), function($tcp_handle, $status){
	uv_close($tcp_handle);
});

uv_run();
````


### resource uv_timer_init([resource $loop])

##### *Description*

initialize timer handle.

##### *Parameters*

*resource $loop*: uv_loop resource.

##### *Return Value*

*resource $timer*: initialized timer resource.

##### *Example*

````php
<?php
$timer = uv_timer_init();
````


### void uv_timer_start(resource $timer, long $timeout, long $repeat, callable $callback)

##### *Description*

initialize timer handle.

##### *Parameters*

*resource $loop*: uv_loop resource.

##### *Return Value*

*resource $timer*: initialized timer resource.

##### *Example*

````php
<?php
$timer = uv_timer_init();
uv_timer_start($timer, 100, 100, function($timer, $status){
	echo "Hello\n";
});

uv_run();
````


### void uv_timer_stop(resource $timer)

##### *Description*

stop specified timer.

##### *Parameters*

*resource $timer*: uv timer resource.

##### *Return Value*

*void*:

##### *Example*

````php
<?php
$timer = uv_timer_init();
uv_timer_start($timer, 100, 100, function($timer, $status){
	echo "Hello\n";
	uv_timer_stop($timer);
});

uv_run();
````


### void uv_timer_again(resource $timer)

##### *Description*

restart timer.

##### *Parameters*

*resource $timer*: uv_timer resource.

##### *Return Value*

*void*:

##### *Example*



### void uv_timer_set_repeat(resource $timer, long $repeat)


### long uv_timer_get_repeat(resource $timer)


### void uv_idle_start(resource $idle, callable $callback)

##### *Description*

start idle callback.

##### *Parameters*

*resource $idle*: uv_idle resource.
*callable $callback*: idle callback.

##### *Return Value*

*void*:

##### *Example*

````php
<?php
$loop = uv_default_loop();
$idle = uv_idle_init();

$i = 0;
uv_idle_start($idle, function($idle_handle, $stat) use (&$i){
    echo "count: {$i}" . PHP_EOL;
    $i++;

    if ($i > 3) {
        uv_idle_stop($idle);
    }
    sleep(1);
});

uv_run();
````



### void uv_getaddrinfo(resource $loop, callable $callback, string $node, string $service, array $hints)


### void uv_idle_stop(resource $idle)

##### *Description*

stop idle callback.

##### *Parameters*

*resource $idle*: uv_idle resource.

##### *Return Value*

*void*:

##### *Example*

````php
<?php
$loop = uv_default_loop();
$idle = uv_idle_init();

$i = 0;
uv_idle_start($idle, function($idle_handle, $stat) use (&$i){
    echo "count: {$i}" . PHP_EOL;
    $i++;

    if ($i > 3) {
        uv_idle_stop($idle);
    }
    sleep(1);
});

uv_run();
````



### resource uv_tcp_init([resource $loop])

##### *Description*

create a tcp socket.

##### *Parameters*

*resource $loop*: loop resource or null. if not specified loop resource then use uv_default_loop resource.

##### *Return Value*

*resource php_uv*: uv resource which initialized for tcp.

##### *Example*

````php
<?php
$tcp = uv_tcp_init();
````



### resource uv_idle_init([resource $loop])

##### *Description*

initialize uv idle handle.

##### *Parameters*

*resource $loop*: uv_loop resource.

##### *Return Value*

*resource $idle*: initialized idle handle.

##### *Example*

````php
<?php
$loop = uv_default_loop();
$idle = uv_idle_init($loop);
````



### resource uv_default_loop()

##### *Description*

return default loop handle.

##### *Parameters*

##### *Return Value*

*resource $loop*:

##### *Example*

````php
<?php
$loop = uv_default_loop();
````



### resource uv_loop_new()

##### *Description*

create a new loop handle.

##### *Parameters*

##### *Return Value*

*resource $loop*:

##### *Example*

````php
<?php
$loop = uv_loop_new();
````



### resource uv_udp_init([resource $loop])

##### *Description*

create a udp socket.

##### *Parameters*

*resource $loop*: loop resource or null. if not specified loop resource then use uv_default_loop resource.

##### *Return Value*

*resource php_uv*: uv resource which initialized for udp.

##### *Example*

````php
<?php
$udp = uv_udp_init();
````



### void uv_udp_bind(resource $resource, resource $address, long $flags)


### void uv_udp_bind6(resource $resource, resource $address, long $flags)


### void uv_udp_recv_start(resource $handle, callable $callback)


### void uv_udp_recv_stop(resource $handle)


### long uv_udp_set_membership(resource $handle, string $multicast_addr, string $interface_addr, long $membership)


### void uv_udp_set_multicast_loop(resource $handle, long $enabled)


### void uv_udp_set_multicast_ttl(resource $handle, long $ttl)


### void uv_udp_set_broadcast(resource $handle, bool $enabled)


### void uv_udp_send(resource $handle, string $data, resource $uv_addr, callable $callback)


### void uv_udp_send6(resource $handle, string $data, resource $uv_addr6, callable $callback)


### bool uv_is_active(resource $handle)


### bool uv_is_readable(resource $handle)


### bool uv_is_writable(resource $handle)


### bool uv_walk(resource $loop, callable $closure[, array $opaque])


### resource uv_pipe_init(resource $loop, long $ipc)


### void uv_pipe_open(resource $handle, long $pipe)


### long uv_pipe_bind(resource $handle, string $name)


### void uv_pipe_connect(resource $handle, string $path, callable $callback)


### void uv_pipe_pending_instances(resource $handle, long $count)


### resource uv_ares_init_options(resource $loop, array $options, long $optmask)


### void ares_gethostbyname(resource $handle, string $name, long $flag, callable $callback)


### array uv_loadavg(void)

##### *Description*

retunrs current loadaverage.

##### *Parameters*

##### *Return Value*

*array $loadaverage*: 

##### *Example*

````php
<?php
var_dump(uv_loadavg());
//array(3) {
//  [0]=>
//  float(1.7421875)
//  [1]=>
//  float(1.427734375)
//  [2]=>
//  float(1.3955078125)
//}
````

##### *Note*

returns array on windows box. (does not support load average on windows)



### double uv_uptime(void)

##### *Description*

returns current uptime.

##### *Parameters*

##### *Return Value*

*long $uptime*: 

##### *Example*

````php
<?php
var_dump(uv_uptime());
//float(1247516)
````



### long uv_get_free_memory(void)

##### *Description*

returns current free memory size.

##### *Parameters*

##### *Return Value*

*long $free*: 

##### *Example*

````php
<?php
var_dump(uv_get_free_memory());
//int(135860224)
````



### long uv_get_total_memory(void)

##### *Description*

returns total memory size.

##### *Parameters*

##### *Return Value*

*long $free*: 

##### *Example*

````php
<?php
var_dump(uv_get_total_memory());
//int(8589934592)
````



### long uv_hrtime(void)

##### *TODO*

check implmentation



### string uv_exepath(void)

##### *Description*

returns current exepath. basically this will returns current php path.

##### *Parameters*

##### *Return Value*

*string $exepath*: 

##### *Example*

````php
<?php
var_dump(uv_exepath());
//string(53) "/Users/chobie/.phpenv/versions/5.4.1-zts-goto/bin/php"
```



### string uv_cwd(void)

##### *Description*

returns current working directory.

##### *Parameters*

##### *Return Value*

*string $cwd*: 

##### *Example*

````php
<?php
var_dump(uv_cwd());
//string(24) "/Users/chobie/src/php-uv"
````



### array uv_cpu_info(void)

##### *Description*

returns current cpu informations.

##### *Parameters*

##### *Return Value*

*array $cpu_info*: 

##### *Example*

````php
<?php
var_dump(uv_cpu_info());
//array(8) {
//  [0]=>
//  array(3) {
//    ["model"]=>
//    string(13) "MacBookPro8,2"
//    ["speed"]=>
//    int(2200)
//    ["times"]=>
//    array(5) {
//      ["sys"]=>
//      int(69952140)
//      ["user"]=>
//      int(38153450)
//      ["idle"]=>
//      int(776709120)
//      ["irq"]=>
//      int(0)
//      ["nice"]=>
//      int(0)
//    }
//  }...
````


### array uv_interface_addresses(void)


### resource uv_spawn(resource $loop, string $command, array $args, array $context, callable $callback)


### void uv_process_kill(resource $handle, long $signal)
TODO: 

### void uv_kill(long $pid, long $signal)


### bool uv_chdir(string $directory)


### resource uv_rwlock_init(void)


### uv_rwlock_rdlock(resource $handle)


### bool uv_rwlock_tryrdlock(resource $handle)


### void uv_rwlock_rdunlock(resource $handle)


### uv_rwlock_wrlock(resource $handle)


### uv_rwlock_trywrlock(resource $handle)


### uv_rwlock_wrunlock(resource $handle)


### uv_lock uv_mutex_init(void) 

### void uv_mutex_lock(uv_lock $lock)

### bool uv_mutex_trylock(uv_lock $lock) 

### uv_lock uv_sem_init(void)


### void uv_sem_post(uv_lock $sem)


### void uv_sem_wait(uv_lock $sem)


### void uv_sem_trywait(uv_lock $sem)


### resource uv_prepare_init(resource $loop)


### void uv_prepare_start(resource $handle, callable $callback)


### void uv_prepare_stop(resource $handle)


### resoruce uv_check_init([resource $loop])


### void uv_check_start(resource $handle, callable $callback)


### void uv_check_stop(resource $handle)


### resource uv_async_init(resource $loop, callable $callback)


### void uv_async_send(resource $handle)


### void uv_queue_work(resource $loop, callable $callback, callable $after_callback)


### resource uv_fs_open(resource $loop, string $path, long $flag, long $mode, callable $callback)


### void uv_fs_read(resoruce $loop, zval $fd, callable $callback)


### void uv_fs_close(resource $loop, zval $fd, callable $callback)


### void uv_fs_write(resource $loop, zval $fd, string $buffer, long $offset, callable $callback)


### void uv_fs_fsync(resource $loop, zval $fd, callable $callback)


### void uv_fs_fdatasync(resource $loop, zval $fd, callable $callback)


### void uv_fs_ftruncate(resource $loop, zval $fd, long $offset, callable $callback)


### void uv_fs_mkdir(resource $loop, string $path, long $mode, callable $callback)


### void uv_fs_rmdir(resource $loop, string $path, callable $callback)


### void uv_fs_unlink(resource $loop, string $path, callable $callback)


### void uv_fs_rename(resource $loop, string $from, string $to, callable $callback)


### void uv_fs_utime(resource $loop, string $path, long $utime, long $atime, callable $callback)


### void uv_fs_futime(resource $loop, zval $fd, long $utime, long $atime callable $callback)


### void uv_fs_chmod(resource $loop, string $path, long $mode, callable $callback)


### void uv_fs_fchmod(resource $loop, zval $fd, long $mode, callable $callback)


### void uv_fs_chown(resource $loop, string $path, long $uid, long $gid, callable $callback)


### void uv_fs_fchown(resource $loop, zval $fd, long $uid, $long $gid, callable $callback)


### void uv_fs_link(resource $loop, string $from, string $to, callable $callback)


### void uv_fs_symlink(resource $loop, string $from, string $to, long $flags, callable $callback)


### void uv_fs_readlink(resource $loop, string $path, callable $callback)


### void uv_fs_stat(resource $loop, string $path, callable $callback)


### void uv_fs_lstat(resource $loop, string $path, callable $callback)


### void uv_fs_fstat(resource $loop, zval $fd, callable $callback)


### uv_fs_readdir(resource $loop, string $path, long $flags, callable $callback)


### void uv_fs_sendfile(resource $loop, zval $in_fd, zval $out_fd, long $offset, long $length, callable $callback)


### resource uv_fs_event_init(resource $loop, string $path, callable $callback, long $flags = 0)


### resource uv_tty_init(resource $loop, zval $fd, long $readable)


### long uv_tty_get_winsize(resource $tty, long &$width, long &$height)


### long uv_tty_set_mode(resource $tty, long $mode)


### void uv_tty_reset_mode(void)


### string uv_tcp_getsockname(resource $uv_sockaddr)


### string uv_tcp_getpeername(resource $uv_sockaddr)


### string uv_udp_getsockname(resource $uv_sockaddr)


### long uv_resident_set_memory(void)


### string uv_ip4_name(resource uv_sockaddr $address)


### string uv_ip6_name(resource uv_sockaddr $address)


### uv uv_poll_init([resource $uv_loop], zval fd)

##### *Description*

initialize poll

##### *Parameters*

*resource $uv_loop*: uv_loop resource.

*mixed $fd*: this expects long fd, PHP's stream or PHP's socket resource.

##### *Return Value*

*resource uv*: uv resource which initialized poll.

##### *Example*

````php
<?php
$fd = fopen("php://stdout","w+");

$poll = uv_poll_init(uv_default_loop(), $fd);

````

##### *Note*

* if you want to use a socket. please use uv_poll_init_socket instead of this. Windows can't handle socket with this function.



### uv uv_poll_init_socket([resource $uv_loop], zval fd)


### uv uv_poll_start(resource $handle, $events, $callback)

##### *Description*

start polling

##### *Parameters*

*resource $poll*: uv poll resource.

*long $events*: UV::READBLE and UV::WRITABLE flags.

*callable $callback*: this callback parameter expects (resource $poll, long $status, long $events, mixed $connection). the connection parameter passes uv_poll_init'd fd.

##### *Return Value*

*void*: 

##### *Example*

````php
<?php
$fd = fopen("php://stdout","w+");

$poll = uv_poll_init(uv_default_loop(), $fd);
uv_poll_start($poll, UV::WRITABLE, function($poll, $stat, $ev, $conn){
        fwrite($conn, "Hello");
        fclose($conn);
        uv_poll_stop($poll);
});

uv_run();
````

##### *Note*

* if you want to use a socket. please use uv_poll_init_socket instead of this. Windows can't handle socket with this function.



### void uv_poll_stop(resource $poll)


### uv uv_fs_poll_init([resource $uv_loop])


### uv uv_fs_poll_start(resource $handle, $callback, string $path, long $interval)


### void uv_fs_poll_stop(resource $poll)


### resource uv_http_parser_init(long $target = UV::HTTP_REQUEST)

##### *Description*

initialize http parser. 

##### *Parameters*

*long $target*: this expects UV::HTTP_REQUEST, UV::HTTP_RESPONSE or UV::HTTP_BOTH.

##### *Return Value*

*resource uv_http*: 

##### *Example*

````php
<?php
$parser = uv_http_parser_init(UV::HTTP_REQUEST);
````



### bool uv_http_parser_execute(resource $parser, string $body, array &$result)

##### *Description*

execute http parser.

##### *Parameters*

*resource $parser*: uv_http_parser resoruce.

*string $body*: http message.

*array &$result*: result array.


##### *Return Value*

*bool finished*: this parser returns false when specified http message is invalid or not enough message.

##### *Example*

````php
<?php
$parser = uv_http_parser_init(UV::HTTP_REQUEST);
if (uv_http_parser_execute($parser, "GET /img/http-parser.png?key=value#frag HTTP/1.1
Host: chobie.net
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:12.0) Gecko/20100101 Firefox/12.0
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Referer: http://chobie.net/
Cookie: key=value
Cache-Control: max-age=0

",$result)) {
	var_dump($result);
//array(6) {
//  ["headers"]=>
//  array(8) {
//    ["Host"]=>
//    string(10) "chobie.net"
//    ["User-Agent"]=>
//    string(81) "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:12.0) Gecko/20100101 Firefox/12.0"
//    ["Accept-Language"]=>
//    string(14) "en-us,en;q=0.5"
//    ["Accept-Encoding"]=>
//    string(13) "gzip, deflate"
//    ["Connection"]=>
//    string(10) "keep-alive"
//    ["Referer"]=>
//    string(18) "http://chobie.net/"
//    ["Cookie"]=>
//    string(9) "key=value"
//    ["Cache-Control"]=>
//    string(9) "max-age=0"
//  }
//  ["QUERY_STRING"]=>
//  string(35) "/img/http-parser.png?key=value#frag"
//  ["path"]=>
//  string(20) "/img/http-parser.png"
//  ["query"]=>
//  string(9) "key=value"
//  ["fragment"]=>
//  string(4) "frag"
//  ["REQUEST_METHOD"]=>
//  string(3) "GET"
//}
}

````