src/native_client_sdk/src/doc/devguide/coding/nacl_io.rst

   1 .. _nacl_io:
   2
   3 ###################
   4 The nacl_io Library
   5 ###################
   6
   7 .. contents::
   8   :local:
   9   :backlinks: none
  10   :depth: 2
  11
  12 Introduction
  13 ============
  14
  15 ``nacl_io`` is a utility library that provides implementations of standard
  16 C APIs such as POSIX I/O (``stdio.h``) and BSD sockets (``sys/socket.h``).
  17 Its primary function is to allow code that uses these standard APIs to be
  18 compiled and used in a Native Client module. The library is included as part
  19 of Native Client SDK and is implemented in on top of Pepper API.
  20
  21 Since Native Client modules cannot access the host machine's file system
  22 directly, nacl_io provides several alternative filesystem types which
  23 can be used by the application. For example, the Chrome browser supports the
  24 `HTML5 File System API
  25 <http://www.html5rocks.com/en/tutorials/file/filesystem/>`_ which provides
  26 access to a protected area of the local file system. This filesystem can
  27 be accessed by an HTML page using JavaScript commands, and also by a Native
  28 Client module using the Pepper :doc:`File IO API <file-io>`. With nacl_io
  29 a Native Client application can mount an HTML5 filesystem and access it via
  30 standard POSIX I/O function such as ``fopen``, ``fseek``, ``fread``,
  31 ``fwrite``, and ``fclose``, or their low level UNIX counterparts ``open``,
  32 ``lseek``, ``read``, ``write`` and ``close``.
  33
  34 As well as the HTML5 file system, nacl_io provides several other file system
  35 types which are described in the table below:
  36
  37 =========== ==================================================================
  38 File System Description
  39 =========== ==================================================================
  40 memfs       An in-memory file system
  41 html5fs     An HTML5 local file system, which can be persistent or temporary
  42 http        Maps files on a remote webserver into the local filesystem.
  43 dev         A file system containing special files (e.g.: ``/dev/null``)
  44 =========== ==================================================================
  45
  46 Using nacl_io
  47 =============
  48
  49 Using nacl_io is mostly just a matter of using the standard POSIX C library
  50 functions. However, there are some steps required to initialize the library
  51 and setup the filesystem mounts. In general the following steps will be needed
  52 to use nacl_io in a NaCl application:
  53
  54 #. Link the application with the nacl_io library (``-lnacl_io``)
  55 #. Initialize nacl_io at startup using the ``nacl_io_init_ppapi`` or
  56    ``nacl_io_init`` functions.
  57 #. Mount any desired filesystems using the ``mount`` function. The arguments
  58    to ``mount`` for the different filesystem types are detailed in
  59    ``include/nacl_io/nacl_io.h``.
  60 #. If you are going to mount an HTML5 file system, be sure to allocate space
  61    for it. You can either set the ``unlimitedStorage`` permission in the app's
  62    Web Store manifest file, or call the HTML5 QuotaManagement API. These
  63    options are explained in the :ref:`File IO documentation <quota_management>`.
  64 #. Make sure that file and socket API calls are all made from the background
  65    thread. This is because the main Pepper thread does not support the blocking
  66    behavior needed by the POSIX I/O operations.
  67
  68 The nacl_io demo
  69 ================
  70
  71 Building and running the demo
  72 -----------------------------
  73
  74 The demo application launches a Native Client module that mounts three file
  75 systems and displays a set of controls that let you work with them:
  76
  77 .. image:: /images/nacl_io1.png
  78
  79 Follow these steps to build and run the demo:
  80
  81 * Open a terminal in the demo directory::
  82
  83     $ cd $NACL_SDK_ROOT/examples/demo/nacl_io
  84
  85 * run the demo::
  86
  87     $ make run
  88
  89 Once the demo is running, try these operations:
  90
  91 #. select the fopen command (when you select a command the fields in the line
  92    below will change according to the command)
  93 #. type in the filename ``/persistent/test``
  94 #. check the write checkbox and press the fopen button
  95 #. select the fwrite command and select the file ``/persistent/test`` in the
  96    menu that appears below on the left
  97 #. enter some data and press the fwrite button
  98 #. select the fclose command, be sure the file ``/persistent/test`` is selected
  99    in the menu, and press the fclose button
 100 #. select the fopen command
 101 #. type in the filename ``/persistent/test``
 102 #. check the fread checkbox and press the fopen button
 103 #. select the fread command, be sure the file /persistent/test is selected in
 104    the menu, enter a byte count, and press the fread button
 105
 106 A look at the code
 107 ------------------
 108
 109 The demo is written C and comprises three files.
 110
 111 nacl_io_demo.c
 112 ^^^^^^^^^^^^^^
 113
 114 This is the demo's main file. The code here creates and initializes the Native
 115 Client module instance. The Pepper function ``Instance_DidCreate`` initializes
 116 nacl_io and mounts an HTML5 filesystem at ``/persistent``.
 117
 118 .. naclcode::
 119
 120   static PP_Bool Instance_DidCreate(PP_Instance instance,
 121                                     uint32_t argc,
 122                                     const char* argn[],
 123                                     const char* argv[]) {
 124     g_instance = instance;
 125     nacl_io_init_ppapi(instance, get_browser_interface);
 126     mount(
 127         "",  /* source */
 128         "/persistent",  /* target */
 129         "html5fs",  /* filesystemtype */
 130         0,  /* mountflags */
 131         "type=PERSISTENT,expected_size=1048576");  /* data specific to the html5fs type */
 132
 133     pthread_create(&g_handle_message_thread, NULL, &HandleMessageThread, NULL);
 134     InitializeMessageQueue();
 135
 136     return PP_TRUE;
 137   }
 138
 139 Space is allocated to the ``/persistent`` file system after the module is
 140 initialized. This is accomplished by the ``domContentLoaded`` function in
 141 the file ``example.js``. This script is included in the module's html page (see
 142 ``examples/demo/index.html``):
 143
 144 .. naclcode::
 145
 146   function domContentLoaded(name, tc, config, width, height) {
 147     navigator.webkitPersistentStorage.requestQuota(window.PERSISTENT, 1024 * 1024,
 148         function(bytes) {
 149           common.updateStatus(
 150               'Allocated ' + bytes + ' bytes of persistant storage.');
 151           common.createNaClModule(name, tc, config, width, height);
 152           common.attachDefaultListeners();
 153         },
 154         function(e) { alert('Failed to allocate space') });
 155   }
 156
 157 The ``Instance_DidCreate`` function also creates a worker thread that receives
 158 messages sent from the html page and performs the specified file system
 159 operations. The logic for the worker thread is encoded in the other two files,
 160 described below.
 161
 162 queue.c
 163 ^^^^^^^
 164
 165 This file implements a circular queue that is used to receive messages from the
 166 browser UI to the Native Client module. The file system commands in the
 167 enqueued messages are executed on the worker thread. This keeps blocking calls
 168 (like fread) off the main Native Client thread, which is a good thing. The
 169 queue is initialized in nacl_io_demo.c ``Instance_DidCreate``.
 170
 171 handlers.c
 172 ^^^^^^^^^^
 173
 174 This file implements the stdio calls associated with the commands sent from the
 175 browser. There is a separate ``Handle*`` function for each command: fopen,
 176 fclose, fseek, fread, fwrite. The handlers are called from the
 177 ``HandleMessage`` function in nacl_io_demo.c, which runs in the worker
 178 thread managing the message queue. The code for the ``fwrite`` handler appears
 179 below. Notice that it does not contain any PPAPI calls and looks like
 180 "ordinary" C code.
 181
 182
 183 .. naclcode::
 184
 185   int HandleFwrite(int num_params, char** params, char** output) {
 186     FILE* file;
 187     const char* file_index_string;
 188     const char* data;
 189     size_t data_len;
 190     size_t bytes_written;
 191
 192     if (num_params != 2) {
 193       *output = PrintfToNewString("Error: fwrite takes 2 parameters.");
 194       return 1;
 195     }
 196
 197     file_index_string = params[0];
 198     file = GetFileFromIndexString(file_index_string, NULL);
 199     data = params[1];
 200     data_len = strlen(data);
 201
 202     if (!file) {
 203       *output = PrintfToNewString("Error: Unknown file handle %s.",
 204                                   file_index_string);
 205       return 2;
 206     }
 207
 208     bytes_written = fwrite(data, 1, data_len, file);
 209
 210     *output = PrintfToNewString("fwrite\1%s\1%d", file_index_string,
 211                                 bytes_written);
 212     return 0;
 213   }
 214
 215 Reference information
 216 =====================
 217
 218 The example discussed here is included in the SDK in the directory
 219 ``examples/demo/nacl_io``.
 220
 221 The nacl_io library is included in the SDK toolchain and is not a part of the
 222 Pepper API. For reference information related to the nacl_io interface see
 223 its header file in the SDK directory, located at
 224 ``include/nacl_io/nacl_io.h``.
 225
 226 For more about the HTML5 file system read the `specification
 227 <http://dev.w3.org/2009/dap/file-system/pub/FileSystem/>`_.