This is the README for Libhansock (http://github.com/toymachine/libhansock)

Libhansock is general client library for HandlerSocket written in C.

The goal of Libhansock is to provide efficient low-level plumbing for accessing HandlerSocket enabled MySQL servers.

It should be easy to build higher level abstractions on top of Libhansock (for instance for PHP, Python, Ruby etc.)

Libhansock provides a fast and efficient IO implementation for talking concurrently with multiple HS servers (using non-blocking asynchronous IO, based on the 'poll' system call). It uses a 'batch' abstraction in order to support pipeline-ing (e.g. send more than 1 command to HS in a single operation), and finally a consistent hashing implementation (Ketama) is provided for partitioning keys across servers.

The low-level library knows about and validates HS results, but does not restrict you in what commands you send trough it, e.g. you can/must format commands yourself. This allows the library to be used with any new and upcoming HS versions without updates, as long as the format of the results does not change.

The public C API is documented in libhansock/hansock.h and an example is given in test.c (make c_test)

Basically,

1. Commands are written into Batches;
2. Batches are associated with Connections trough an Executor; Executor::add(connection, batch)
3. The total operation is performed within a configurable timeout by calling Executor::execute(timeout)

4. When execution returns, batches will contain replies that can be read out using an iterator; Batch::get_replies()

   Batch batch = Batch_new(); Executor executor = Executor_new(); Connection *connection = Connection_new("127.0.0.1:9998");

   //setup some commands char cmd[1024];

   sprintf(cmd, "P 1 testdb testtable PRIMARY test_id,test_string ");

   Batch_write(batch, cmd, strlen(cmd), 1);

   sprintf(cmd, "1 = 1 %d ", pk);

   Batch_write(batch, cmd, strlen(cmd), 1);

   //associate batch with connections Executor_add(executor, connection, batch);

   //execute it if(Executor_execute(executor, 500) > 0) { //all ok ReplyIterator replies = Batch_get_replies(batch); while(ReplyIterator_next(replies)) { ReplyType reply_type; char reply_data; size_t reply_len; ReplyIterator_get_reply(replies, &reply_type, &reply_data, &reply_len); printf("reply type: %d, data: '%.s' ", (int)reply_type, reply_len, reply_data); ReplyIterator children = ReplyIterator_child_iterator(replies); if(children != NULL) { //have to check for NULL, not all replies have children! while(ReplyIterator_next(children)) { ReplyType child_reply_type; char child_reply_data; size_t child_reply_len; ReplyIterator_get_reply(children, &child_reply_type, &child_reply_data, &child_reply_len); printf(" child reply type: %d, data: '%.s' ", (int)child_reply_type, child_reply_len, child_reply_data); } ReplyIterator_free(children); } } ReplyIterator_free(replies); }

   //release all resources Executor_free(executor); Batch_free(batch); Connection_free(connection);

Error Handling

Module Errors

• per thread 'last' error Connection/Batch Errors
• aborted batch holds error Executor Errors
• errors with polling