diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2017-10-26 16:45:12 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2017-10-26 16:45:12 (GMT) |
commit | 6054f36bb658916bd231b9002efb94444e2871c8 (patch) | |
tree | a815500ec9bf0e100f4075a825213605c382def0 /doc/intro.html | |
download | blt-6054f36bb658916bd231b9002efb94444e2871c8.zip blt-6054f36bb658916bd231b9002efb94444e2871c8.tar.gz blt-6054f36bb658916bd231b9002efb94444e2871c8.tar.bz2 |
Squashed 'xpa/' content from commit d6a54301
git-subtree-dir: xpa
git-subtree-split: d6a543018b46c5a6c47b5ff91e0e131549595ca6
Diffstat (limited to 'doc/intro.html')
-rw-r--r-- | doc/intro.html | 148 |
1 files changed, 148 insertions, 0 deletions
diff --git a/doc/intro.html b/doc/intro.html new file mode 100644 index 0000000..f9c9947 --- /dev/null +++ b/doc/intro.html @@ -0,0 +1,148 @@ +<!-- =defdoc xpaintro xpaintro n --> +<HTML> +<HEAD> +<TITLE>Introduction to XPA</TITLE> +</HEAD> +<BODY> + +<!-- =section xpaintro NAME --> +<H2><A NAME="xpaintro">XPAIntro: Introduction to the XPA Messaging System</A></H2> + +<!-- =section xpaintro SYNOPSIS --> +<H2>Summary</H2> +<P> +A brief introduction to the XPA messaging system, which provides +seamless communication between all kinds of Unix event-driven +programs, including X programs, Tcl/Tk programs, and Perl programs. + +<!-- =section xpaintro DESCRIPTION --> +<H2>Description</H2> +<P> +The XPA messaging system provides seamless communication between all +kinds of Unix programs, including X programs, Tcl/Tk programs, and +Perl programs. It also provides an easy way for users to communicate +with these XPA-enabled programs by executing XPA client commands in +the shell or by utilizing such commands in scripts. Because XPA works +both at the programming level and the shell level, it is a powerful +tool for unifying any analysis environment: users and programmers have +great flexibility in choosing the best level or levels at which to +access XPA services, and client access can be extended or modified +easily at any time. + +<P> +A program becomes an XPA-enabled server by defining named points of +public access through which data and commands can be exchanged with +other client programs (and users). Using standard TCP sockets as +a transport mechanism, XPA supports both single-point and broadcast +messaging to and from these servers. It supports direct communication +between clients and servers, or indirect communication via an +intermediate message bus emulation program. Host-based access control +is implemented, as is as the ability to communicate with XPA servers +across a network. + +<P> +XPA implements a layered interface that is designed to be useful both +to software developers and to users. The interface consists of a +library of XPA client and server routines for use in programs and a +suite of high-level user programs built on top of these libraries. +Using the XPA library, access points can be added to +<A HREF="./tcl.html#">Tcl/Tk</A> +programs, +<A HREF="./xt.html#">Xt</A> +programs, or to Unix programs that use the XPA event loop or any +event loop based on select(). Client access subroutines can be added +to any Tcl/Tk or Unix program. Client access also is supported at the +command line via a suite of high-level programs. + +<P> +The major components of the XPA layered interface are: +<UL> +<LI> +A set of XPA server routines, centered on +<A HREF="./server.html#xpanew">XPANew(),</A> +which are used by XPA server programs to tag public access points with +string identifiers and to register send and receive callbacks for +these access points. + +<LI> +A set of XPA client routines, centered on the +<A HREF="./client.html#xpaset">XPASet()</A> +and +<A HREF="./client.html#xpaget">XPAGet(),</A> +which are used by external client applications to exchange data and +commands with an XPA server. + +<LI> +High-level programs, centered on +<A HREF="./programs.html#xpaset">xpaset</A> +and +<A HREF="./programs.html#xpaget">xpaget,</A> +which allow data +and information to be exchanged with XPA server programs from the +command line and from scripts. These programs have the command syntax: +<PRE> + [data] | xpaset <XPA name> [qualifiers ...] + xpaget <XPA name> [qualifiers ...] +</PRE> +<LI> +An XPA name server program, +<A HREF="./xpans.html">xpans,</A> +through which XPA access point names are +registered by servers and distributed to clients. +</UL> + +<P> +Defining an XPA access point is easy: a server application calls +<A HREF="./server.html#xpanew">XPANew(),</A> +<A HREF="./server.html#xpacmdnew">XPACmdNew(),</A> +or the experimental +<A HREF="./server.html#xpainfonew">XPAInfoNew()</A> +routine to +create a named public access point. An XPA service can specify "send" +and "receive" callback procedures (or an "info" procedure in the case +of XPAInfoNew()) to be executed by the program when an external +process either sends data or commands to this access point or requests +data or information from this access point. Either of the callbacks +can be omitted, so that a particular access point can be specified as +read-only, read-write, or write-only. Application-specific client +data can be associated with these callbacks. Having defined one or +more public access points in this way, an XPA server program enters +its usual event loop (or uses the standard XPA event loop). + +<P> +Clients communicate with these XPA public access points +using programs such as +<A HREF="./programs.html#xpaget">xpaget</A>, +<A HREF="./programs.html#xpaset">xpaset</A>, and +<A HREF="./programs.html#xpainfo">xpainfo</A> +(at the command line), +or routines such as +<A HREF="./client.html#xpaget">XPAGet(),</A> +<A HREF="./client.html#xpaset">XPASet(),</A> +and +<A HREF="./client.html#xpainfo">XPAInfo()</A> +within a program. Both methods require specification of the name of +the access point. The xpaget program returns data or other +information from an XPA server to its standard output, while the +xpaset program sends data or commands from its standard input to an +XPA application. The corresponding API routines set/get data to/from +memory, returning error messages and other info as needed. If a +<A HREF="./template.html">template</A> +is used to specify the access point name (e.g., "ds9*"), then +communication will take place with all servers matching that template. + +<p> +Please note that XPA currently is not thread-safe. All XPA calls must be +in the same thread. + +<!-- =section xpaintro SEE ALSO --> +<!-- =text See xpa(n) for a list of XPA help pages --> +<!-- =stop --> + +<P> +<A HREF="./help.html">Go to XPA Help Index</A> + +<H5>Last updated: March 10, 2007</H5> +</BODY> +</HTML> + |