summaryrefslogtreecommitdiffstats
path: root/xpa/doc/pod/xpamainloop.pod
blob: 4fabf8e06d20eabf065dffe1f77e20e68cd1e9b2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
=pod

=head1 NAME



B<XPAMainLoop: optional main loop for XPA>



=head1 SYNOPSIS





  #include <xpa.h>

  void XPAMainLoop();





=head1 DESCRIPTION




Once XPA access points have been defined, a program must enter an
event loop to watch for requests from external programs. This can be
done in a variety of ways, depending on whether the event loop is
processing events other than XPA events.  In cases where there are no
non-XPA events to be processed, the program can simply call the
XPAMainLoop() event loop.  This loop is implemented essentially as
follows (error checking is simplified in this example):

  FD_ZERO(&readfds);
  while( XPAAddSelect(NULL, &readfds) ){
    if( sgot = select(swidth, &readfds, NULL, NULL, NULL) >0 )
      XPAProcessSelect(&readfds, 0);
    else
      break;
    FD_ZERO(&readfds);
  }


The XPAAddSelect() routine sets up the select() readfds variable so
that select() will wait for I/O on all the active XPA channels.  It
returns the number of XPAs that are active; the loop will end when
there are no active XPAs. The standard select() routine is called to
wait for an external I/O request.  Since no timeout struct is passed
in argument 5, the select() call hangs until there is an external
request.  When an external I/O request is made, the XPAProcessSelect()
routine is executed to process the pending requests.  In this routine,
the maxreq value determines how many requests will be processed: if
maxreq <=0, then all currently pending requests will be processed.
Otherwise, up to maxreq requests will be processed.  (The most usual
values for maxreq is 0 to process all requests.)


If a program has its own Unix select() loop, then XPA access points can
be added to it by using a variation of the standard XPAMainLoop:

  XPAAddSelect(xpa, &readfds);
  [app-specific ...]
  if( select(width, &readfds, ...) ){
    XPAProcessSelect(&readfds, maxreq);
    [app-specific ...]
    FD_ZERO(&readfds);
  }


XPAAddSelect() is called before select() to add the access points.
If the first argument is NULL, then all active XPA access points
are added. Otherwise only the specified access point is added.
After select() is called, the XPAProcessSelect() routine can be called
to process XPA requests.  Once again, the maxreq value determines how
many requests will be processed: if maxreq <=0, then all currently
pending requests will be processed.  Otherwise, up to maxreq requests
will be processed.


XPA access points can be added to
Xt event loops (using XtAppMainLoop())
and
Tcl/Tk event loops (using vwait and the Tk loop).
When using XPA with these event loops, you only need to call:

int XPAXtAddInput(XtAppContext app, XPA xpa)

or

  int XPATclAddInput(XPA xpa)

respectively before entering the loop.




=head1 SEE ALSO



See xpa(n) for a list of XPA help pages


=cut