Merge branch 'asyncops'

docs/ops.markdown

@@ -1789,3 +1789,98 @@ an integral number of seconds, `_n` returns a fractional amount.
 * `x_posixerrno()`
 
 Returns an int that corresponds to the value of POSIX's errno.
+
+# Asynchronous operations
+
+The various asynchronous operations, such as timers and asynchronous I/O, take
+a concurrent queue to push a work item into at an appropriate time. This may
+be a code object to be invoked, or it may be an array of a code item and some
+arguments to supply to it. Asynchronous operations are represented by some
+object with the AsyncTask REPR, the exact details of which are highly
+specific to a given backend. The type to use for that is given as $handle_type.
+
+[As of 2014.04, these are very new and subject to revision and additions.]
+
+## cancel
+* `cancel(AsyncTask $handle)`
+
+Takes something with the AsyncTask REPR and tries to cancel it, if it
+is possible to do so. If it is somehow not possible (for example, the
+operation already completed anyway), then nothing will happen. This is to
+avoid race conditions.
+
+## timer
+* `($queue, $schedulee, int $timeout, int $repeat, $handle_type)`
+
+Starts a timer. If timeout is zero, the $schedulee is immediately pushed to
+the queue. Otherwise, it is pushed after the timeout period. If repeat is
+non-zero, after the initial timeout period it will then be pushed again at
+the repeat interval. Returns an object of type $handle_type, which has a
+AsyncTask REPR. Cancellation stops the timer ever repeating again.
+
+## signal
+* `signal($queue, $schedulee, int [nqp::cosnt::SIG_], $handle_type)`
+
+Sets up a signal handler for the given signal. Whenever it occurs, an
+array is pushed to the queue containg the schedulee and the signal number.
+Cancel to stop handling it.
+
+## watchfile
+* `watchfile($queue, $schedulee, str $filename, $handle_type)`
+
+Watches an individual file for changes. Pushes the an array to the queue
+when a change is detected, consisting of the schedulee, the filename that
+changed if provided by the underlying watcher mechanism, a 0 if the file
+changed, and a 1 if it was renamed. Cancel to stop watching.
+
+## asyncconnect
+* `asyncconnect($queue, $schedulee, str $host, int $port, $handle_type)`
+
+Creates an asynchronous client socket and commences a connection operation.
+Upon connection, the queue will be passed an array consisting of the
+schedulee, a handle if the connection was successful (a type object if not)
+and an error string (some type object if no error). Returns an AsyncTask
+representing the connection attempt.
+
+## asynclisten
+* `asynclisten($queue, $schedulee, str $host, int $port, $handle_type)`
+
+Creates an asynchronous server socket listening on the specified host and port.
+Each time a connection arrives, the queue will be passed an array consisting of
+the schedulee and the newly created asynchronous socket, for communicating with
+the connecting client. Returns an AsyncTask that can be cancelled to stop
+listening, or throws an exception if there is an error starting to listen.
+
+## asyncwritestr
+* `asyncwritestr($handle, $queue, $schedulee, str $to_write, $handle_type)`
+
+Writes a string to some handle capable of asynchronous operations. Once the write
+is complete, the queue will be passed an array consisting of the schedulee, an
+integer containing the number of bytes written or a type object if there was an
+error, and a string containing an error or some type object if none.
+
+## asyncwritebytes
+* `asyncwritebytes($handle, $queue, $schedulee, $to_write, $handle_type)`
+
+Writes a byte array to some handle capable of asynchronous operations. Once the write
+is complete, the queue will be passed an array consisting of the schedulee, an
+integer containing the number of bytes written or a type object if there was an error,
+and a string containing an error or some type object if none.
+
+## asyncreadchars
+* `asyncreadchars($handle, $queue, $schedulee, $handle_type)`
+
+Starts reading chars from the handle. When a packet is received and decoded, an
+array will be pushed to the queue containing the schedulee, a squence number that
+starts at 0, the string if anything was decoded (type object on error) and an error
+string (some type object if no error). If EOF is reached, a sequence number of -1
+is sent. Cancel to stop reading.
+
+## asyncreadbytes
+* `asyncreadbytes($handle, $queue, $schedulee, $buf_type, $handle_type)`
+
+Starts reading bytes from the handle. When a packet is received, a $buf_type will be
+constructed and point to the received memory. An array will be pushed to the queue
+containing the schedulee, a sequence number that starts at 0, the buffer or just its
+type object on error, and an error string (type object if no error). If EOF is reached,
+a sequence number of -1 is sent. Cancel to stop reading.

src/vm/moar/QAST/QASTOperationsMAST.nqp

@@ -1710,6 +1710,11 @@ my %const_map := nqp::hash(
     'STAT_PLATFORM_DEVTYPE',   -5,
     'STAT_PLATFORM_BLOCKSIZE', -6,
     'STAT_PLATFORM_BLOCKS',    -7,
+
+    'SIG_INT',                  1,
+    'SIG_BREAK',                2,
+    'SIG_HUP',                  3,
+    'SIG_WINCH',                4,
 );
 QAST::MASTOperations.add_core_op('const', -> $qastcomp, $op {
     if nqp::existskey(%const_map, $op.name) {
@@ -2392,6 +2397,15 @@ QAST::MASTOperations.add_core_moarop_mapping('queuepoll', 'queuepoll');
 
 # asynchrony related ops
 QAST::MASTOperations.add_core_moarop_mapping('timer', 'timer');
+QAST::MASTOperations.add_core_moarop_mapping('cancel', 'cancel', 0);
+QAST::MASTOperations.add_core_moarop_mapping('signal', 'signal');
+QAST::MASTOperations.add_core_moarop_mapping('watchfile', 'watchfile');
+QAST::MASTOperations.add_core_moarop_mapping('asyncconnect', 'asyncconnect');
+QAST::MASTOperations.add_core_moarop_mapping('asynclisten', 'asynclisten');
+QAST::MASTOperations.add_core_moarop_mapping('asyncwritestr', 'asyncwritestr');
+QAST::MASTOperations.add_core_moarop_mapping('asyncwritebytes', 'asyncwritebytes');
+QAST::MASTOperations.add_core_moarop_mapping('asyncreadchars', 'asyncreadchars');
+QAST::MASTOperations.add_core_moarop_mapping('asyncreadbytes', 'asyncreadbytes');
 
 # MoarVM-specific compilation ops
 QAST::MASTOperations.add_core_moarop_mapping('masttofile', 'masttofile', 2);

tools/build/MOAR_REVISION

@@ -1 +1 @@
-2014.04-8-g5889985
+2014.04-23-g61c8cc7