GNU.WIKI: The GNU/Linux Knowledge Base

  [HOME] [PHP Manual] [HowTo] [ABS] [MAN1] [MAN2] [MAN3] [MAN4] [MAN5] [MAN6] [MAN7] [MAN8] [MAN9]

  [0-9] [Aa] [Bb] [Cc] [Dd] [Ee] [Ff] [Gg] [Hh] [Ii] [Jj] [Kk] [Ll] [Mm] [Nn] [Oo] [Pp] [Qq] [Rr] [Ss] [Tt] [Uu] [Vv] [Ww] [Xx] [Yy] [Zz]


NAME

       xdf_write - Write samples to a xDF file

SYNOPSIS

       #include <xdfio.h>

       ssize_t xdf_write(struct xdf* xdf, size_t ns, ...);

DESCRIPTION

       xdf_write()  writes  ns samples to the xDF file referenced by xdf. This
       file   should   have   been   opened   with    mode    XDF_WRITE    and
       xdf_prepare_arrays(3)  should  have  been  successfully  called  on it.
       xdf_write() will fail otherwise).

       The data to be  added  should  be  contained  in  arrays  specified  by
       pointers  provided  in  the variable list of arguments of the function.
       The function expects the same number of arrays as specified by previous
       call  to xdf_define_arrays(3). The internal organisation of the data in
       the  arrays  should  have  been  specified  previously  with  calls  to
       xdf_set_chconf(3).

       In  addition,  it  is  important to note that none of the arrays should
       overlap.

RETURN VALUE

       The function returns the number of the samples  successfully  added  to
       the  xDF file in case of success. Otherwise -1 is returned and errno is
       set appropriately.

ERRORS

       EINVAL xdf is NULL

       EPERM  No successfull call to xdf_prepare_transfer(3) have been done on
              xdf or it has been opened using the mode XDF_READ.

       EFBIG  An   attempt   was  made  to  write  a  file  that  exceeds  the
              implementation-defined maximum file size or the  process's  file
              size  limit,  or to write at a position past the maximum allowed
              offset.

       EINTR  The call was  interrupted  by  a  signal  before  any  data  was
              written; see signal(7).

       EIO    A low-level I/O error occurred while modifying the inode.

       ENOSPC The device containing the xDF file has no room for the data.

       ESTALE Stale  file  handle.  This error can occur for NFS and for other
              file systems

PERFORMANCE CONSIDERATION

       By design of the library, a call to xdf_write() is "almost" ensured  to
       be  executed  in  a linear time, i.e. given a fixed configuration of an
       xDF file, for the same number of samples to be passed, a call xdf_write
       will  almost take always the same time to complete. This time increases
       linearly with the number of samples.  This  insurance  is  particularly
       useful  for  realtime  processing  of data, since storing the data will
       impact the main loop in a predictible way.

       This is achieved by double buffering the data for writing. A front  and
       a  back  buffer  are  available:  the  front  buffer is filled with the
       incoming data, and swapped with the back buffer when  full.  This  swap
       signals  a  background thread to convert, reorganise, scale and save to
       the disk the data contained in the full  buffer  making  it  afterwards
       available for the next swap.

       This  approach  ensures a linear calltime of xdf_write() providing that
       I/O subsystem is not saturated neither all processing units  (cores  or
       processors), i.e. the application is neither I/O bound nor CPU bound.

DATA SAFETY

       The library makes sure that data written to xDF files are safely stored
       on stable storage on a regular basis but because of  double  buffering,
       there  is  a risk to loose data in case of problem. However, the design
       of the xdf_write() ensures that if  a  problem  occurs  (no  more  disk
       space,  power supply cut), at most two records of data plus the size of
       the chunks of data supplied to the function will be lost.

       As an example, assuming you record a xDF file at 256Hz using records of
       256  samples and you feed xdf_write() with chunks of 8 samples, you are
       ensured to receive notification of failure after at  most  520  samples
       corresponding  to  a  lose  of at most a little more than 2s of data in
       case of problems.

EXAMPLE

              /* Assume xdf references a xDF file opened for writing whose
              channels source their data in 2 arrays of float whose strides
              are the length of respectively 4 and 6 float values,
              i.e. 16 and 24 bytes (in most platforms)*/
              #define NS    3
              float array1[NS][4], array2[NS][6];
              unsigned int strides = {4*sizeof(float), 6*sizeof(float)};
              unsigned int i;

              xdf_define_arrays(xdf, 2, strides);
              if (xdf_prepare_transfer(xdf))
                   return 1;

              for (i=0; i<45; i+=NS) {
                   /* Update the values contained in array1 and array2*/
                   ...

                   /* Write the values to the file */
                      if (xdf_write(xdf, NS, array1, array2))
                        return 1;
              }

              xdf_close(xdf);

SEE ALSO

       xdf_set_chconf(3), xdf_define_arrays(3), xdf_prepare_transfer(3)



  All copyrights belong to their respective owners. Other content (c) 2014-2018, GNU.WIKI. Please report site errors to webmaster@gnu.wiki.
Page load time: 0.116 seconds. Last modified: November 04 2018 12:49:43.