sys/man/2/ioproc

   1 .TH IOPROC 2
   2 .SH NAME
   3 closeioproc,
   4 iocall,
   5 ioclose,
   6 ioflush,
   7 iointerrupt,
   8 iodial,
   9 ioopen,
  10 ioproc,
  11 ioread,
  12 ioreadn,
  13 iosleep,
  14 iowrite \- slave I/O processes for threaded programs
  15 .SH SYNOPSIS
  16 .PP
  17 .de XX
  18 .ift .sp 0.5
  19 .ifn .sp
  20 ..
  21 .EX
  22 .ta \w'Ioproc* 'u
  23 #include <u.h>
  24 #include <libc.h>
  25 #include <thread.h>
  26 .sp
  27 typedef struct Ioproc Ioproc;
  28 .sp
  29 Ioproc* ioproc(void);
  30 .XX
  31 int     ioopen(Ioproc *io, char *file, int omode);
  32 int     ioclose(Ioproc *io, int fd);
  33 long    ioread(Ioproc *io, int fd, void *a, long n);
  34 long    ioreadn(Ioproc *io, int fd, void *a, long n);
  35 long    iowrite(Ioproc *io, int fd, void *a, long n);
  36 int     iodial(Ioproc *io, char *addr, char *local, char *dir, int *cdfp);
  37 int     iosleep(Ioproc *io, long n);
  38 .XX
  39 int     ioflush(Ioproc *io);
  40 void    iointerrupt(Ioproc *io);
  41 void    closeioproc(Ioproc *io);
  42 .XX
  43 long    iocall(Ioproc *io, long (*op)(va_list *arg), ...);
  44 .EE
  45 .SH DESCRIPTION
  46 .PP
  47 These routines provide access to I/O in slave procs.
  48 Since the I/O itself is done in a slave proc, other threads
  49 in the calling proc can run while the calling thread
  50 waits for the I/O to complete.
  51 .PP
  52 .I Ioproc
  53 forks a new slave proc and returns a pointer to the
  54 .B Ioproc
  55 associated with it.
  56 .I Ioproc
  57 uses
  58 .I mallocz
  59 and
  60 .IR proccreate ;
  61 if either fails, it calls
  62 .I sysfatal
  63 rather than return an error.
  64 .PP
  65 .IR Ioopen ,
  66 .IR ioclose ,
  67 .IR ioread ,
  68 .IR ioreadn ,
  69 .IR iowrite ,
  70 .IR iosleep ,
  71 and
  72 .IR iodial
  73 execute the
  74 similarly named library or system calls
  75 (see
  76 .IR open (2),
  77 .IR read (2),
  78 and
  79 .IR dial (2))
  80 in the slave process associated with
  81 .IR io .
  82 .PP
  83 .I Iointerrupt
  84 interrupts the next or currently executing call in the I/O proc.  If
  85 there was no call executing, the interrupt will stay pending and the
  86 next I/O call will get interrupted.
  87 .PP
  88 .I Ioflush
  89 executes a non-op in the I/O proc. It is commonly called after
  90 .IR iointerrupt
  91 to clear a pending interrupt.
  92 .PP
  93 .I Closeioproc
  94 terminates the I/O proc and frees the associated
  95 .BR Ioproc .
  96 .PP
  97 .I Iocall
  98 is a primitive that may be used to implement
  99 more slave I/O routines.
 100 .I Iocall
 101 arranges for
 102 .I op
 103 to be called in
 104 .IR io 's
 105 proc, with
 106 .I arg
 107 set to the variable parameter list,
 108 returning the value that
 109 .I op
 110 returns.
 111 .SH EXAMPLE
 112 Relay messages between two file descriptors,
 113 counting the total number of bytes seen:
 114 .IP
 115 .EX
 116 .ta +\w'xxxx'u +\w'xxxx'u +\w'xxxx'u
 117 int tot;
 118
 119 void
 120 relaythread(void *v)
 121 {
 122         int *fd, n;
 123         char buf[1024];
 124         Ioproc *io;
 125
 126         fd = v;
 127         io = ioproc();
 128         while((n = ioread(io, fd[0], buf, sizeof buf)) > 0){
 129                 if(iowrite(io, fd[1], buf, n) != n)
 130                         sysfatal("iowrite: %r");
 131                 tot += n;
 132         }
 133         closeioproc(io);
 134 }
 135
 136 void
 137 relay(int fd0, int fd1)
 138 {
 139         int fd[4];
 140
 141         fd[0] = fd[3] = fd0;
 142         fd[1] = fd[2] = fd1;
 143         threadcreate(relaythread, fd, 8192);
 144         threadcreate(relaythread, fd+2, 8192);
 145 }
 146 .EE
 147 .LP
 148 If the two
 149 .I relaythread
 150 instances were running in different procs, the
 151 common access to
 152 .I tot
 153 would be unsafe.
 154 .PP
 155 Implement
 156 .IR ioread :
 157 .IP
 158 .EX
 159 static long
 160 _ioread(va_list *arg)
 161 {
 162         int fd;
 163         void *a;
 164         long n;
 165
 166         fd = va_arg(*arg, int);
 167         a = va_arg(*arg, void*);
 168         n = va_arg(*arg, long);
 169         return read(fd, a, n);
 170 }
 171
 172 long
 173 ioread(Ioproc *io, int fd, void *a, long n)
 174 {
 175         return iocall(io, _ioread, fd, a, n);
 176 }
 177 .EE
 178 .SH SOURCE
 179 .B /sys/src/libthread/io*.c
 180 .SH SEE ALSO
 181 .IR dial (2),
 182 .IR open (2),
 183 .IR read (2),
 184 .IR sleep (2),
 185 .IR thread (2)
 186