Thursday, April 21, 2016

Blank Character is Not Null Character

Perhaps, it is partly because I'm not a native English speaker and partly because I forgot that the devil is in the details that I inadvertently wrote code that supposed to initialize a variable with blank characters with null characters.

Blank characters refer to whitespace character (https://en.wikipedia.org/wiki/Whitespace_character), not the null character (https://en.wikipedia.org/wiki/Null_character). In many cases, acceptable blank character for program input is space, which has a value of 20h in ASCII and 40h in EBCDIC. Well, this is not obvious for me at first until I'm debugging some code in an EBCDIC environment. 

So, next time you read an API documentation that says *BLANK*, it doesn't refer to NULL ('\0') character, but it refers to one of the whitespace character which in many cases refer to SPACE (' ').

As a bonus, these are some usable character conversion tables:
http://www.astrodigital.org/digital/ebcdic.html (this one explicitly states SPACE character as BLANK)

Sunday, March 20, 2016

[How-to] Copy Contents of Tmux Pane to File

There are many cases where you might want to copy part of (or the entire) contents of a tmux pane into file for further usage. This post explains how to that. Before we proceed, you need to be aware that my tmux key binding is probably different from yours, see: http://darmawan-salihun.blogspot.co.id/2015/02/zsh-tmux-configuration-for-arch-linux.html. I'm using vi mode-keys.

The steps to copy contents of a tmux pane are as follows:
  1. Enter copy mode. The key combo to enter copy mode depends on your tmux configuration, but the principle never change: press your tmux prefix key combo--in my case, this is Ctrl+A--and then press your tmux copy mode key-in my case the key is Escape. If you look at my tmux configuration file linked above, I should press: Ctrl+A, then Escape to enter tmux copy mode
  2. Select the text that you want to copy. I'm using the v key to select the text because that's how my tmux key binding is configured (~/.tmux.conf: bind -t vi-copy 'v' begin-selection). This is how it looks like once I have selected some text in copy mode with vi-like keys (the selected text is in yellow background):
    tmux copy mode
  3. Copy the selected text into tmux buffer. I'm using y (yank) key to select the text because that's how my tmux key binding is configured (~/.tmux.conf: bind -t vi-copy 'y' copy-selection). Now the selected text is in tmux buffer.
You can "save" contents of the tmux buffer to a file with this command:
$ tmux save-buffer -b [the_buffer_yo_want_to_save] -a [name_of_the_file_you_want_to_append_the_buffer_to]
If you want to just overwrite the contents of the "target" file with the tmux buffer contents, you can omit the -a flag. You can select your "source" tmux buffer before saving the tmux buffer contents by using the command completion key in your shell (in my case TAB -- I'm using zsh). Tmux buffer possibly contains more than one buffer if you previously "copy" something into the buffer, either inadvertently or on-purpose. This is how tmux buffer looks like in my shell as I'm trying to save one of its entries:
Tmux "copy buffer" number 0 to number 10

Anyway, you can also bind keys to the tmux save buffer command in order to make the text available for GUI application as in my tmux.conf shown in the link above. This is the configuration snippet (I'm using icccm clipboard for that):
# extra commands for interacting with the ICCCM clipboard
bind C-c run "tmux save-buffer - | xclip -i -sel clipboard"
bind C-v run "tmux set-buffer \"$(xclip -o -sel clipboard)\"; tmux paste-buffer"
That's it. I hope the explanation is clear enough because there are many explanation on the web that's not quite well-suited for newbie.

Thursday, February 18, 2016

C Macro 101: Stringizing Operator and Token Pasting Operator

Present day C language has evolved to the point where we can be productive writing code in it. Perhaps, many still views that writing code in C is tedious compared to writing code in other higher-level language. I think, that's a subjective view. Perhaps, only functional languages have higher productivity compared to C for most non-system-programming.

Two of the "productivity features" in C that I found indispensable at the moment are the stringizing operator (#) and token-pasting operator (a.k.a concatenation operator) (##). Both of these operators can be used in C macros only, you cannot use it outside of C macros. However, both are very powerful tools to create function templates in C. Yes, you read that right. Function templates are not just for C++ programmers. C programmers also has a sort of function template via C macros, despite it's a little "rudimentary" compared to C++.

Most stringizing and token-pasting tutorials out there don't provide useful code snippets with regard to the "real" power of these operators. This post aims to fill that gap. Without further ado, let's get to the code. You can clone the complete sample code used in this post from https://github.com/pinczakko/sample_token_pasting
#include <stdio.h>
#include <assert.h>

typedef enum {
 PEEK_REQUEST_ITEM,
 PEEK_REPLY_ITEM,
 MOD_REQUEST_ITEM,
 MOD_REPLY_ITEM
}ITEM_TYPE;

struct queue_item {
 ITEM_TYPE type;
 char payload[32];
};

struct handler {
 int identifier;
 int (*process_data) (void* data);
};

#define PRINT_FUNC_NAME \
do { \
 printf("In function: %s() \n", __func__); \
} while (0);

static inline int process_peek_request(const struct queue_item *const
          peek_req,
          struct handler *p)
{
 /** Algorithm A ...  */
 PRINT_FUNC_NAME
 return 0;
}

static inline int process_peek_reply(const struct queue_item *const
        peek_rep,
        struct handler *p)
{
 /** Algorithm B ...  */
 PRINT_FUNC_NAME
 return 0;
}

static inline int process_modification_request(const struct queue_item *const
          modification_req,
          struct handler *p)
{
 /** TODO: Invalidate cached items taking part in the MOD transaction **/

 /** TODO: Enqueue the MOD request to egress_port_output_queue */

 /** TODO: Notify egress_port thread to consume the MOD request */

 PRINT_FUNC_NAME

 return 0;/** Success */

 error:
 return -1;/** Failed */
}

static inline int process_modification_reply(const struct queue_item *const
        modification_rep,
        struct handler *p)
{
 /** TODO: Enqueue the MOD reply to ingress_port_output_queue */

 /** TODO: Notify ingress_port thread to consume the MOD reply */

 PRINT_FUNC_NAME

 return 0;/** Success */

 error:
 return -1;/** Failed */
}

#define PROCESS_DEQUEUED_ITEM(MESSAGE, TYPE) \
static inline int process_dequeued_##MESSAGE(const struct queue_item *const MESSAGE,\
         struct handler *p) \
{ \
 assert((MESSAGE != NULL) && (p != NULL)); \
 \
 assert((MESSAGE->type == PEEK_##TYPE) || \
        (MESSAGE->type == MOD_##TYPE)); \
 \
 PRINT_FUNC_NAME \
 \
 if (MESSAGE->type == PEEK_##TYPE) { \
  printf("Processing PEEK " #MESSAGE "\n"); \
  return process_peek_##MESSAGE(MESSAGE, p); \
 \
 } else if (MESSAGE->type == MOD_##TYPE) { \
  printf("Processing MOD " #MESSAGE "\n"); \
  return process_modification_##MESSAGE(MESSAGE, p); \
 \
 } else { \
  printf("Warning: Unknown " #MESSAGE " type!\n"); \
  return -1; /** Failed */ \
 } \
}

/** Token-pasted function instance to handle request message */
PROCESS_DEQUEUED_ITEM(request, REQUEST_ITEM)

/** Token-pasted function instance to handle reply message */
PROCESS_DEQUEUED_ITEM(reply, REPLY_ITEM)

int main (int argc, char * argv[])
{
 int i; 

 struct queue_item req_item[2], rep_item[2];
 struct handler h;

 req_item[0].type = PEEK_REQUEST_ITEM;
 req_item[1].type = MOD_REQUEST_ITEM;

 rep_item[0].type = PEEK_REPLY_ITEM;
 rep_item[1].type = MOD_REPLY_ITEM;

 for (i = 0; i < 2; i++) {
  process_dequeued_request(&req_item[i], &h);
 }

 for (i = 0; i < 2; i++) {
  process_dequeued_reply(&rep_item[i], &h);
 }

 return 0;
}
The code above will produce two different functions,  process_dequeued_request() and process_dequeued_reply(), respectively, to  handle request and reply. The algorithm used by both functions is very similar, the differences are only in function naming, parameters naming and constant naming. Therefore, it is natural to use token-pasting and stringizing operators in the code. In C++, you would use  C++ template. You can achieve the same thing in C with token-pasting (##) and stringizing operator (#).

The stringizing operator (#) basically creates a C string from the C macro parameter. For example, if you pass reply as parameter to a C macro, the C preprocessor will produce "reply" (C string -- including the double quotes) as output if the stringizing operator is applied to the macro parameter. Perhaps, it's a bit hard to understand. Let's look at the sample code above. In this line:
PROCESS_DEQUEUED_ITEM(reply, REPLY_ITEM)
we asked the preprocessor to instantiate the process_dequeued_reply() function. In the process_dequeued_reply() function, the code uses the stringizing operator like so:
printf("Processing PEEK " #MESSAGE "\n");
After GCC preprocessing stage, this function call becomes:
printf("Processing PEEK " "reply" "\n");
As you see, the reply macro input parameter is transformed into "reply", i.e. stringized.
Perhaps, you asked, how can I obtain the preprocessor output? Well, in most compiler, you can obtain the preprocessor output via certain compiler switch(es). In GCC, you can use the -save-temps switch to do so. The GCC preprocessor output is a *.i file with the same name as the source file. In my sample code, the Makefile uses this switch to instruct GCC to place the preprocessor output in the source code directory. I used the indent utility (indent -linux sample_token_pasting.i) to beautify the preprocessor output.
This is an example snippet of the "beautified" preprocessor output from sample_token_pasting.i file:
static inline int process_dequeued_reply(const struct queue_item *const reply,
      struct handler *p)
{
#107 "sample_token_pasting.c" 3 4
 ((
#107 "sample_token_pasting.c"
   (reply !=
#107 "sample_token_pasting.c" 3 4
    ((void *)0)
#107 "sample_token_pasting.c"
   ) && (p !=
#107 "sample_token_pasting.c" 3 4
         ((void *)0)
#107 "sample_token_pasting.c"
   )
#107 "sample_token_pasting.c" 3 4
  )? (void)(0) : __assert_fail(
#107 "sample_token_pasting.c"
          "(reply != ((void *)0)) && (p != ((void *)0))"
#107 "sample_token_pasting.c" 3 4
          , "sample_token_pasting.c", 107,
          __PRETTY_FUNCTION__))
#107 "sample_token_pasting.c"
     ;
#107 "sample_token_pasting.c" 3 4
 ((
#107 "sample_token_pasting.c"
   (reply->type == PEEK_REPLY_ITEM)
   || (reply->type == MOD_REPLY_ITEM)
#107 "sample_token_pasting.c" 3 4
  )? (void)(0) : __assert_fail(
#107 "sample_token_pasting.c"
          "(reply->type == PEEK_REPLY_ITEM) || (reply->type == MOD_REPLY_ITEM)"
#107 "sample_token_pasting.c" 3 4
          , "sample_token_pasting.c", 107,
          __PRETTY_FUNCTION__))
#107 "sample_token_pasting.c"
     ;
 do {
  printf("In function: %s() \n", __func__);
 } while (0);
 if (reply->type == PEEK_REPLY_ITEM) {
  printf("Processing PEEK " "reply" "\n");
  return process_peek_reply(reply, p);
 } else if (reply->type == MOD_REPLY_ITEM) {
  printf("Processing MOD " "reply" "\n");
  return process_modification_reply(reply, p);
 } else {
  printf("Warning: Unknown " "reply" " type!\n");
  return -1;
 }
}
It's a bit unwieldy. However, sometimes you need to be sure that you don't make any silly mistake with your C macro by looking into the preprocessor output.

Let's move to the other operator, the token-pasting operator. This operator basically "paste and concatenate" the macro parameter to create the "target" C token from both the macro parameter and the C token "fragment" in your macro. If you don't truly understand what a C language token yet, please read http://www.help2engg.com/c_tokens and https://msdn.microsoft.com/en-us/library/c6sb2c6b.aspx. The sample code uses the token-pasting operator to create "configurable" C function name and constants. This code:
PROCESS_DEQUEUED_ITEM(reply, REPLY_ITEM)
produces three C tokens: process_dequeued_reply function name, PEEK_REPLY_ITEM constant and MOD_REPLY_ITEM constant. You can see the process clearly in the GCC preprocessor output snippet above. The process_dequeued_ C token "fragment" is concatenated with the value of the MESSAGE macro parameter, which in this macro invocation:
PROCESS_DEQUEUED_ITEM(reply, REPLY_ITEM)
has a value equal to reply. Therefore, the concatenated ("target") C token is process_dequeued_reply. The constants also undergo similar transformation via the TYPE macro parameter.

Anyway, this is the output of the program (compiled from the sample code)
In function: process_dequeued_request() 
Processing PEEK request
In function: process_peek_request() 
In function: process_dequeued_request() 
Processing MOD request
In function: process_modification_request() 
In function: process_dequeued_reply() 
Processing PEEK reply
In function: process_peek_reply() 
In function: process_dequeued_reply() 
Processing MOD reply
In function: process_modification_reply() 
Well, the output just shows which functions are invoked and their order of invocation to clarify the inner working of both stringizing operator and token-pasting operator.

Hopefully, the explanation in this post clarify the power of C stringizing and token-pasting operator.

Tuesday, January 19, 2016

Using Boost C++ Library from C

This post is related to another post: Building C++ Application with Boost Library and Autotools in Linux. If you haven't know how to use Boost C++library in an autotools project, please read that post.

The purpose of this post is to explain what you need to do to use use Boost from your C language code. The following are the steps required to use Boost from C:
  1. Decide which part of Boost that you require in your C application.
  2. Wrap that part of Boost as "convenience" C library.
  3. Link your C application code to the "convenience" library. 
The steps above is easier said than done. Don't worry, I have provided a sample project over at github: https://github.com/pinczakko/boost_spsc_queue_c_wrapper. Just download the code and try to make sense of it.
DISCLAIMER
-----------
- The code assumes that the platform in which it runs has a working pthread implementation.
- The code is not production quality code. Use it at your own risk.
The sample code basically wraps Boost SPSC (single producer single consumer) lockfree queue into a convenience C library and the sample application links to the convenience library.

Anyway, the most important part of the code that you need to understand is the part that "returns" a C++ class as an "opaque" C structure. Probably, it's a quite alien concept. But, I assure you that this alien concept is the core of C<-->C++ interoperability. Below is the relevant code snippets:


//---- START spsc_interface.hpp file -----------------
#ifndef  SPSC_WRAPPER_H
#include "spsc_wrapper.h"
#endif //SPSC_WRAPPER_H 

class spsc_interface {
public:
    explicit spsc_interface();
    explicit spsc_interface(const spsc_interface &);
    ~spsc_interface() {};
//...

};
//---- END spsc_interface.hpp file -----------------

//---- START spsc_wrapper.h file -----------------
#ifdef __cplusplus
extern "C" {
#endif
//...
 typedef struct spsc_interface spsc_interface;

 spsc_interface *create_spsc_interface();

//---- END spsc_wrapper.h file -----------------

//---- START spsc_wrapper.cc file -----------------

#include "spsc_interface.hpp"
#include "spsc_wrapper.h"

#ifdef __cplusplus
extern "C" {
#endif

spsc_interface * create_spsc_interface()
{
    return new spsc_interface();
}

...
#ifdef __cplusplus
}
#endif
//---- END spsc_wrapper.cc file -----------------

As you see above, the wrapper function create_spsc_interface() returns an opaque object of type struct spsc_interface. In fact, this opaque object is a C++ class in disguise as you can see in the spsc_wrapper.cc snippet above. If you ask: How's that possible? Well, the answer lies in the linking process. Let's see the relevant snippets from src/Makefile.am:

wrapper_test_SOURCES = wrapper_test.c 
### Below is just a trick to force using C++ linker
nodist_EXTRA_wrapper_test_SOURCES = dummy.cc 

As you can see, we're not using a C linker to link the entire project, but we use a C++ linker (by tricking autotools ;) . A C++ linker "understand" the idiom used in spsc_wrapper.cc above.