Return to resources.3r CVS log

Up to [Research Unix] / researchv10dc / 630 / man / src / p_man / man3

Annotation of researchv10dc/630/man/src/p_man/man3/resources.3r, revision 1.1

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.