![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to resources.3r CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / 630 / man / src / p_man / man3|
Return to resources.3r CVS log | Up to [Research Unix] / researchv10dc / 630 / man / src / p_man / man3 |
1.1 root 1: .ds ZZ DEVELOPMENT PACKAGE
2: .TH RESOURCES 3R "630 MTG"
3: .XE "request()"
4: .XE "own()"
5: .XE "wait()"
6: .XE "alarm()"
7: .SH NAME
8: resources: request, own, wait, alarm \- routines dealing with resources
9: .SH SYNOPSIS
10: .ft B
11: #include <dmd.h>
12: .sp
13: int request (r)
14: .sp
15: int own ( )
16: .sp
17: int wait (r)
18: .sp
19: void alarm (t)
20: .sp
21: int r;
22: .br
23: unsigned t;
24: .SH DESCRIPTION
25: The above routines deal with the following 630 MTG resources:
26: .PP
27: .PD 0
28: .TP 15
29: .B KBD
30: characters received from the 630 MTG keyboard
31: .TP
32: .B SEND
33: send characters from the 630 MTG to the host
34: .TP
35: .B MOUSE
36: mouse buttons and cursor position
37: .TP
38: .B RCV
39: characters received by 630 MTG from host process
40: .TP
41: .B PSEND
42: send characters to the printer
43: .TP
44: .B CPU
45: 630 MTG cpu
46: .TP
47: .B ALARM
48: alarm has "fired"
49: .TP
50: .B RESHAPED
51: window has been reshaped or moved
52: .TP
53: .B DELETE
54: application is being deleted
55: .TP
56: .B MSG
57: state of message queues has changed
58: .PD
59: .PP
60: .I Request
61: announces a program's intent to use one or more resources
62: and is usually called once early in the program.
63: The
64: .B r
65: argument is a bit vector indicating which resources are being requested.
66: Compose
67: .B r
68: by using the bitwise inclusive OR operator of the
69: above resources (\&\s-1MOUSE\s+1\^|\^\s-1KBD\s+1 means
70: you are referring to the mouse and keyboard resources).
71: .I Request
72: returns a bit vector that indicates those resources for which the request
73: succeeded.
74: .PP
75: Note that if a program calls
76: .I request
77: several times,
78: each \f2request\f1 overrides all previously
79: .IR request ed
80: resources. This means that a resource previously
81: .IR request ed,
82: but not specified in the latest call to
83: .I request ,
84: will no longer be available to the application program.
85: .PP
86: If the keyboard is not requested,
87: characters typed will be sent to the host.
88: If the mouse is not requested,
89: mouse events in the application's window will be interpreted by
90: the terminal's control process (the terminal's control process is the
91: process that displays
92: the main button 3 menu and makes windows top and current when pointed
93: to by button 1).
94: \s-1SEND\s+1 and \s-1CPU\s+1 are always implicitly
95: .IR request ed.
96: .PP
97: A request of \s-1PSEND\s+1 will fail if
98: another application program has already requested it. Currently, \s-1PSEND\s+1
99: is the only resource that may fail a request.
100: \s-1PSEND\s+1 must be requested and owned before sending characters to the
101: printer.
102: .PP
103: Requesting the \s-1DELETE\s+1 resource tells the terminal's control process
104: to not allow a user to delete the applications window from the main button 3
105: menu. Rather, the control process sets a flag which causes
106: \fIown()&\s-1DELETE\s+1\fR to be true. This is intended for
107: use by applications which need to perform some type of cleanup before being
108: deleted. When \fIown()&\s-1DELETE\s+1\fR becomes true, it is the responsibility
109: of the application to perform its cleanup and delete itself (see example below).
110: .PP
111: The
112: .I own
113: function
114: returns a bit vector indicating which resources are ready to be serviced.
115: .SK
116: .PP
117: The
118: .I wait
119: function
120: suspends the application, enabling others to run,
121: until at least one of the resources in the bit vector \fIr\fR
122: is ready for service.
123: The return value is a bit vector indicating which resources are
124: ready for service.
125: Applications wishing to give up the processor to enable other applications to
126: run may call
127: \f2wait\f3(\s-1CPU\s+1)\f1.
128: In this case,
129: .I wait
130: will always return as soon as all other applications have had a chance to run.
131: .PP
132: The
133: .I alarm
134: function
135: starts a timer which will ``fire''
136: .B t
137: ticks (60ths of a second) in the future.
138: Calling
139: .I alarm
140: implicitly \fIrequest\fRs the
141: .B \s-1ALARM\s+1 .
142: The resource
143: .B \s-1ALARM\s+1
144: can be used to check the status of the timer.
145: The
146: \fIown\fR( ) \fB\s-1&ALARM\s+1\f1
147: call
148: will indicate whether or not the alarm timer has fired.
149: A
150: \fIwait\fR(ALARM) call allows the application to give up the CPU
151: until the specified number of ticks has elapsed.
152: An
153: \fIalarm\fR(0)
154: call cancels a previous call to \fIalarm\fR.
155: .PP
156: An
157: .I alarm
158: call
159: does not interfere with
160: .I sleep
161: and vice versa.
162: .PP
163: The call \fIwait\fR (RESHAPED) will suspend the application until the
164: application's window has been either moved or reshaped. The MOVED and
165: RESHAPED bits of the application's state variable (\fIP->state\fR) can be read to determine
166: which of the two has occurred. If the window was moved, both the MOVED and
167: RESHAPED bits are set; only the RESHAPED bit is set if the window was
168: reshaped. The application is responsible for
169: clearing the state variable MOVED and RESHAPED bits regardless of whether
170: they are read or not. Subsequent \fIwait\fR (RESHAPED) calls will return
171: immediately if the application has not cleared the MOVED and RESHAPED bits.
172: RESHAPED is always implicitly requested.
173: .PP
174: The call \fIwait\fR (MSG) will suspend the application until the state of
175: any of the message queues associated with the application changes. A list
176: of message queue identifiers is maintained for each application. A message
177: queue identifier is entered into this list during a call by the
178: application to the function msgget when either a message queue is
179: created or an identifier for an existing message queue is retrieved.
180: Once added to this list, a message queue identifier is
181: removed from the list only when the message queue is deleted. The message
182: queue can be deleted by any running application with a call to the function msgctl or
183: is deleted automatically if it was created with the NO_SAVE option and the
184: creating application is deleted or exits.
185: .PP
186: The function calls \fIown\fR(MSG) and \fIwait\fR(MSG) will return the MSG
187: bit true in the returned bit vector
188: after any of three state changes occur to any of the message queues
189: associated with the application: 1) a message queue when
190: added to the application's list already has one or more messages on it,
191: 2) a message is received at a message queue, or 3) a
192: message queue on the list is deleted.
193: This condition remains true until cleared by a call to the function msgctl
194: to examine a message queue or by a call to the function msgrcv to receive
195: a message from a queue.
196: Note that several applications may simultaneously be waiting for the same
197: message queue.
198: If a message arrives at the queue, all of the waiting applications will be
199: restarted.
200: If the first application that is restarted removes the arrived message from
201: the queue and does not replace it back on the queue with a call to the function
202: msgsnd, the other applications that were waiting will find no message when they
203: are restarted.
204: Similarly, an application may find no message queue when it is restarted if
205: the queue was deleted by another application.
206: If an application sends a message to a message queue that is on its
207: own message queue list, the wait condition becomes true for it also.
208: .SH EXAMPLE
209: The following program fragment shows how an application
210: can give up button 3 processing
211: to the terminal's control process. This is how applications who request the
212: mouse but do not use button 3 can let the main button 3 menu be displayed.
213: .PP
214: Note that the \f(CWsleep(2)\fR below is necessary because the terminal's
215: control process
216: runs only once every tick (60th of a second) of the realtime clock.
217: .PP
218: .RS 3
219: .nf
220: .ft CM
221: #include <dmd.h>
222:
223: main()
224: {
225: int r;
226:
227: r = request (\s-1MOUSE\s+1);
228: if (button3()){
229: request (r & ~\s-1MOUSE\s+1); /* release the mouse */
230: sleep (2);/* sleep(2) because the control process */
231: /* only runs once every clock tick */
232: request (r);
233: }
234: }
235: \fR
236: .fi
237: .RE
238: .PP
239: The following program shows how to use the \s-1DELETE\s+1 resource.
240: This program will ring the terminals bell before it is deleted.
241: Typically, rather than ringing the bell, some application specific
242: cleanup would be performed.
243: .PP
244: .RS 3
245: .nf
246: .ft CM
247: #include <dmd.h>
248:
249: main()
250: {
251: request(DELETE|MOUSE);
252:
253: for(;;) {
254: wait(DELETE|MOUSE);
255: if(own()&DELETE) {
256: ringbell(); /* usually some cleanup */
257: delete(); /* delete me */
258: }
259: }
260: }
261: \fR
262: .fi
263: .RE
264: .PP
265: The following code fragment shows how to use the RESHAPED resource. Upon
266: return from \fIwait\fR it tests the state variable to determine if the
267: window was moved or reshaped. Depending on which occurred, an appropriate
268: flag is set and the state variable is cleared.
269: .PP
270: .RS 3
271: .nf
272: .ft CM
273: #include <dmd.h>
274: .
275: .
276: int moved=0;
277: int reshaped=0;
278: .
279: .
280: wait(RESHAPED);
281: if (P->state&MOVED) {
282: moved++;
283: P->state &= ~(MOVED|RESHAPED);
284: }
285: else if ((P->state&RESHAPED) && !(P->state&MOVED)) {
286: reshaped++;
287: P->state &= ~RESHAPED;
288: }
289: .
290: .
291: \fR
292: .fi
293: .RE
294: .SH SEE ALSO
295: msgctl(3L), msgget(3L), msgop(3L), sleep(3R), state(3R).
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.