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