Creating a Message Queue
A Q4M table represents a single queue. A row of a Q4M table represents a single message. To create a message queue, use CREATE TABLE statement with the engine name ``queue''.
CREATE TABLE my_queue (v1 int not null, v2 varchar(255)) ENGINE=queue;If you need to route messages to more than one subscriber, create table for each of them. You can create any number of Q4M tables.
Sending a Message
To send a message, use INSERT command as you would do on a ordinally SQL table.
INSERT INTO my_queue (v1, v2) VALUES (3, "hello world!");
Receiving a Message
Q4M uses two modes to represent a message queue. In NON-OWNER mode, Q4M tables operate as an ordinally table. In OWNER mode, only the row owned by the connection becomes visible. Three functions are used to switch between views, and to block until messages become available.
By calling the queue_wait function, Q4M table enters OWNER mode. Once entering the OWNER mode, only one row (at maximum) becomes SELECTable, exclusively from the connection, i.e. a row owned by a connection becomes invisible to other connections. When Q4M table is empty, queue_wait function will block until any rows become available. If the function timeouts, no row will be visible by SELECT queries.
After handling the row, clients should either call queue_end function or queue_wait function. The row owned by the connection will be automatically removed from the table. By calling the queue_end function, the table will return to NON-OWNER mode. By calling the queue_wait function, a new row to be handled will become available. When clients fail in handling the row, it should call queue_abort function, that returns the owned-row to the table so that it could be handled by other clients.
Below is a skelton code of a client written in perl subscribing to a Q4M table.
while (1) {
# wait until any data becomes avialable (or timeouts)
$dbh->do('select queue_wait("test_db.test_table")')
or die $dbh->errstr;
# receive data (only one row becomes ready at once)
if (my @row = $dbh->selectrow_array('select * from test_table')) {
# handle the row
unless (process_row(@row)) {
# if failed, return the row to queue
$dbh->do('select queue_abort()')
or die $dbh->errstr;
}
}
}
# tidy up
$dbh->do('select queue_end()')
or die $dbh->errstr;