| blob | ddcfe3d98d33c88708a63194ecf6192e8f75126a |
1 <!-- -->
2 <HTML>
4 <HEAD>
12 <HR>
18 <TABLE>
19 <TD>
20 <UL>
24 </UL>
25 </TD>
27 <TD>
28 <UL>
32 </UL>
33 </TD>
34 </TABLE>
36 These services play two roles in ACE:<P>
38 <UL>
39 <LI> They provide reusable components for common distributed system
40 tasks such as logging, naming, locking, and time synchronization.<P>
43 wrappers</A>, <A HREF="http://www.dre.vanderbilt.edu/~schmidt/ACE-papers.html#reactor">Reactor</A>,
44 <A HREF="http://www.dre.vanderbilt.edu/~schmidt/ACE-papers.html#config">Service Configurator</A>, <A
48 components. <P> </UL>
50 The heart of the ACE network services is the <A
52 Configurator</A>, which is an object-oriented framework that automates
53 the configuration and reconfiguration of multi-service daemons. All
54 the ACE network services are configured using the Service
56 documentation</a> for more information on installing and testing the
57 ACE network services.<P>
59 <P><HR>
63 A Naming Service associates names with values in a distributed
64 system. Clients can query these values using these names as keys. Such
67 context is a collection that contains a set of name bindings in which
68 each name is unique. Different names can be bound to the same value in
69 the same or different naming contexts at the same time. There are
70 three types of naming contexts: <P>
72 <OL>
73 <LI> Process Local Naming Context: Name bindings are accessible from
74 processes with the same name running on the same host. <P>
75 <LI> Node Local Naming Context: Name bindings are accessible from all
76 processes running on the same host. <P>
77 <LI> Network Local Naming Context: Name bindings are accessible from
78 all processes running on any machine within a (sub)network. <P>
79 </OL>
81 <P>
82 To bind a name is to create a name binding in a given context.
83 Querying a value using a name determines the value associated with the
84 name in a given context. Note that a name is always bound relative to
85 a context. Thus, there are no absolute names. <P>
87 The following are the key classes in the ACE Naming Service: <P>
89 <UL>
92 This is the main class ``entry point'' into the Naming Service. It is
93 used both by client processes and by server process. It manages access
94 to the appropriate Name/Binding database (that is the file where
95 Name/Bindings are stored) and it also manages the communication
96 between a client process and the server (by using class Name_Proxy,
97 which is a private member of Naming_Context). If a client process
98 runs on the same host as the server no IPC is necessary because the
99 Naming_Context uses shared memory. <P>
103 The Name_Acceptor allocates in its handle_input() routine a new
104 instance of class Name_Handler on the heap, and accepts connections
105 into this Name_Handler. <P>
109 The class Name_Handler represents the server side of communication
110 between client and server. It interprets incoming requests to the
111 Net_Local namespace and delegates the requests to its own
112 Naming_Context (which is the Net_Local namespace on the current
113 host). For communication it uses the helper classes Name_Request and
114 Name_Reply.<P>
118 The ACE Naming Service uses ACE_WString String classes since it must
119 handle wide character strings in order to support
120 internationalization. <P>
121 </UL>
123 The following describes how to configure the Name_Server server and
124 client test applications. <P>
126 <UL>
128 Configuring a Name_Server server or client requires specifying all or
129 some of the following parameters. These parameters can be passed in to
130 main through command line as follows:<P>
135 </TD>
138 </TD>
141 </TD>
142 <TR>
145 </TD>
149 </TD>
151 PROC_LOCAL
152 </TD>
153 <TR>
156 </TD>
158 Specify the server hostname (needed by Name Server clients for
159 PROC_LOCAL naming context)
160 </TD>
162 ACE_DEFAULT_SERVER_HOST
163 </TD>
164 <TR>
167 </TD>
169 Port number where the server process expects requests <BR>
170 </TD>
172 ACE_DEFAULT_SERVER_PORT
173 </TD>
174 <TR>
177 </TD>
179 Directory that holds the NameBinding databases <BR>
180 </TD>
182 ACE_DEFAULT_NAMESPACE_DIR
183 </TD>
184 <TR>
187 </TD>
189 Name of the client process
190 </TD>
192 argv[0]
193 </TD>
194 <TR>
197 </TD>
199 Name of the database. NameBindings for the appropriate naming context
201 </TD>
204 </TD>
205 <TR>
208 </TD>
210 Turn debugging on/off
211 </TD>
213 0 (off)
214 </TD>
215 <TR>
218 </TD>
220 Turn tracing on/off
221 </TD>
223 0 (off)
224 </TD>
225 <TR>
228 </TD>
230 Turn verbose on/off
231 </TD>
233 0 (off)
234 </TD>
236 </TABLE>
237 <P>
240 <OL>
241 <LI> Here is what a config file would look like for starting up a
242 server at port 20222 using NET_LOCAL naming context with database
243 called MYDATABSE located in directory /tmp:
245 <PRE> <CODE>
246 dynamic Naming_Service Service_Object *
247 ../lib/netsvcs:_make_ACE_Name_Acceptor()
248 "-p 20222 -c NET_LOCAL -l /tmp -s MYDATABASE"
249 </PRE> </CODE>
251 <LI> Here is what a config file would look like for starting up a
252 client that connects to a Name Server running on host
253 tango.cs.wustl.edu at port 20222:
255 <PRE> <CODE>
256 dynamic Naming_Service_Client Service_Object *
257 ../lib/netsvcs:_make_Client_Test()
258 "-h tango.cs.wustl.edu -p 20222"
259 </PRE> </CODE>
260 </OL>
262 Note:<P>
264 <UL>
265 <LI> Values for parameters can also be passed in using environment
266 variables. For example, instead of specifying absolute hostname or
267 port numbers in the config file, we can use $HOST and $PORT,
268 respectively, in the file (assuming that these environment variables
269 have been set). <P>
271 <LI> If the environment variable LD_LIBRARY_PATH (in the case of UNIX)
272 or PATH (in the case of Win32) contains the path to the shared object
273 files or dll, then the config file can be further simplified. Instead
274 of specifying a path to the shared object or dll, only the name of the
275 shared object or dll would suffice. That is, the Service Configurator
276 makes use of LD_LIBRARY_PATH (on UNIX) or PATH (on Win32) to look for
277 the shared object files or dlls.
279 </UL>
281 </UL>
283 <P><HR><P>
287 Time Service provides accurate, fault-tolerant clock synchronization
288 for computers collaborating in local area networks and wide area
289 networks. Synchronized time services are important in distributed
290 systems that require multiple hosts to maintain accurate global
291 time. The architecture of the distributed time service contains the
292 following Time Server, Clerk, and Client components: <P>
294 <UL>
296 Clerks. <P>
299 the correct time, calculates the approximate correct time using one of
300 several distributed time algorithms and updates its own local system
301 time. <P>
304 a Clerk to provide consistency with the notion of time used by clients
305 on other hosts. <P>
306 </UL>
307 <P>
308 The following are the key classes in the ACE Time Service: <P>
310 <UL>
313 TS_Server_Handler represents the server side of communication between
314 clerk and server. It interprets incoming requests for time updates,
315 gets the system time, creates a reply in response to the request and
316 then sends the reply to the clerk from which it received the request.
317 For communication it uses the helper class Time_Request.<P>
321 TS_Server_Acceptor allocates in its handle_input routine a new instance
322 of class TS_Server_Handler on the heap, and accepts connections into this
323 TS_Server_Handler.<P>
327 TS_Clerk_Handler represents the clerk side of communication between
328 clerk and server. It generates requests for time updates every timeout
329 period and then sends these requests to all the servers it is
330 connected to asynchronously. It receives the replies to these requests
331 from the servers through its handle_input method and then adjusts the
332 time using the roundtrip estimate. It caches this time, which is
333 subsequently retrieved by TS_Clerk_Processor.<P>
337 TS_Clerk_Processor creates a new instance of TS_Clerk_Handler for
338 every server connection it needs to create. It periodically calls
339 send_request() of every TS_Clerk_Handler to send a request for time
340 update to all the servers. In the process, it retrieves the latest
341 time cached by each TS_Clerk_Handler and then uses it to compute its
342 notion of the local system time.<P>
346 Currently, updating the system time involves taking the average of all
347 the times received from the servers.<P>
348 </UL>
350 The following is a description of how to configure the Time Server
351 clerk and server services: <P>
353 <UL>
357 Configuring a server requires specifying the port number of the
358 server. This can be specified as a command line argument as follows: <P>
362 <P>
363 A clerk communicates with one or more server processes. To communicate
364 with the server process, a client needs to know the INET_Addr, where
365 the server offers its service. The configuration parameters namely the
366 server port and server host are passed as command line arguments when
367 starting up the clerk service as follows: <P>
370 <P>
371 Note that multiple servers can be specified in this manner for the
372 clerk to connect to when it starts up. The server name and the port
373 number need to be concatenated and separated by a ":". In addition,
374 the timeout value can also be specified as a command line argument as
375 follows:
376 <P>
378 -t timeout
380 <P>
381 The timeout value specifies the time interval at which the clerk
382 should query the servers for time updates.
383 <P>
384 By default a Clerk does a non-blocking connect to a server. This can
385 be overridden and a Clerk can be made to do a blocking connect by
386 using the -b flag.
387 <P>
390 <OL>
391 <LI> Here is what a config file would look like for starting up a
392 server at port 20202:
394 <PRE> <CODE>
395 dynamic Time_Service Service_Object *
396 ../lib/netsvcs:_make_ACE_TS_Server_Acceptor()
397 "-p 20202"
398 </PRE> </CODE>
400 <LI> Here is what a config file would look like for starting up a
401 clerk that needs to connect to two servers, one at tango and one at
402 lambada:
404 <PRE> <CODE>
405 dynamic Time_Server_test Service_Object *
406 ../lib/netsvcs:_make_ACE_TS_Clerk_Connector ()
407 "-h tango:20202 -h lambada:20202 -t 4"
408 </PRE> </CODE>
409 </OL>
411 Note:<P>
412 <UL>
413 <LI> These files would vary if the services are run on NT. For
414 example, instead of using *.so, we would have to use *.dll.<P>
415 <LI> Values for parameters can also be passed in using environment
416 variables. For example, instead of specifying absolute hostname or
417 port numbers in the config file, we can use $HOST and $PORT,
418 respectively, in the file (assuming that these environment variables
419 have been set). <P>
420 <LI> If the environment variable LD_LIBRARY_PATH (in the case of UNIX)
421 or PATH (in the case of Win32) contains the path to the shared object
422 files or dll, then the config file can be further simplified. Instead
423 of specifying a path to the shared object or dll, only the
424 name of the shared object or dll would suffice. That is, the Service
425 Configurator makes use of LD_LIBRARY_PATH (on UNIX) or PATH (on Win32)
426 to look for the shared object files or dlls.
427 </UL>
428 <P>
430 </UL>
432 <P><HR><P>
435 The ACE Token Service provides local and remote mutexes and
436 readers/writer locks. For information regarding the deadlock
437 detection algorithm, check out ACE_Token_Manager.h. For information
438 about an implementation of the Composite Pattern for Tokens, check out
439 Token_Collection.h. The classes which implement the local and remote
440 synchronization primitives are listed below:<P>
442 <UL>
445 This class is a more general-purpose synchronization mechanism
447 mutex" semantics, where a thread that owns the token can
448 reacquire it without deadlocking. In addition, threads that
449 are blocked awaiting the token are serviced in strict FIFO
450 order as other threads release the token (SunOS 5.x mutexes
451 don't strictly enforce an acquisition order). Lastly,
452 ACE_Local_Mutex performs deadlock detection on acquire
453 calls.<p>
457 This is the remote equivalent to ACE_Local_Mutex. The
458 Remote_Mutex class offers methods for acquiring, renewing, and
459 releasing a distributed synchronization mutex. Similar to
460 ACE_Local_Mutex, ACE_Remote_Token_Proxy offers recursive
461 acquisition, FIFO waiter ordering, and deadlock detection. It
462 depends on the Token Server for its distributed synchronization
463 semantics.<p>
467 This class implements the reader interface to canonical
468 readers/writer locks. Multiple readers can hold the lock
469 simultaneously when no writers have the lock. Alternatively,
470 when a writer holds the lock, no other participants (readers or
471 writers) may hold the lock. This class is a more
472 general-purpose synchronization mechanism than SunOS 5.x
473 RLocks. For example, it implements "recursive RLock"
474 semantics, where a thread that owns the token can reacquire it
475 without deadlocking. In addition, threads that are blocked
476 awaiting the token are serviced in strict FIFO order as other
477 threads release the token (SunOS 5.x RLockes don't strictly
478 enforce an acquisition order).<P>
482 This class implements the writer interface to canonical
483 readers/writer locks. Multiple readers can hold the lock
484 simultaneously when no writers have the lock. Alternatively,
485 when a writer holds the lock, no other participants (readers or
486 writers) may hold the lock. This class is a more
487 general-purpose synchronization mechanism than SunOS 5.x WLock.
488 For example, it implements "recursive WLock" semantics, where a
489 thread that owns the token can reacquire it without
490 deadlocking. In addition, threads that are blocked awaiting
491 the token are serviced in strict FIFO order as other threads
492 release the token (SunOS 5.x WLocks don't strictly enforce an
493 acquisition order).<P>
497 This is the remote equivalent to ACE_Local_RLock. Multiple
498 readers can hold the lock simultaneously when no writers have
499 the lock. Alternatively, when a writer holds the lock, no
500 other participants (readers or writers) may hold the lock.
501 ACE_Remote_RLock depends on the ACE Token Server for its
502 distributed synchronization semantics.<P>
506 This is the remote equivalent to ACE_Local_WLock.<P>
507 </UL>
509 The Token Server provides distributed mutex and readers/writer lock
510 semantics to the ACE Token library. ACE_Remote_Mutex,
511 ACE_Remote_RLock, and ACE_Remote_WLock, are proxies to the Token
512 Server. The following are the key classes in the ACE Token
513 Server:<P>
515 <UL>
518 The Token_Acceptor is a Token_Handler factory. It accepts
519 connections and passes the service responsibilities off to a
520 new Token_Handler.<p>
524 This class is the main class ``entry point'' of the ACE Token service. It
525 receives token operation requests from remote clients and turns
526 them into calls on local tokens (acquire, release, renew, and
527 remove). In OMG CORBA terminology, it is an ``Object Adapter.'' It also
528 schedules and handles timeouts that are used to support "timed
529 waits." Clients used timed waits to bound the amount of time
530 they block trying to get a token.<P>
531 </UL>
533 The following describes how to configure the Token Server:<P>
534 <UL>
537 The only parameter that the Token Server takes is a listen port
538 number. You can specify a port number by passing a "-p
539 <port_number>" to the application. This can be done via the
540 svc.conf file.<P>
544 Here is an example svc.conf entry that dynamically loads the
545 Token Server specifying port number to listen on for client
546 connections:<P>
548 <code><pre>
549 dynamic Token_Service Service_Object *
550 ../lib/netsvcs:_make_ACE_Token_Acceptor()
551 "-p 10202"
552 </code></pre>
553 <P>
555 </UL>
556 Note:<P>
557 <UL>
558 <LI> These files would vary if the services are run on NT. For
559 example, instead of using *.so, we would have to use *.dll.<P>
560 <LI> Values for parameters can also be passed in using environment
561 variables. For example, instead of specifying absolute hostname or
562 port numbers in the config file, we can use $HOST and $PORT,
563 respectively, in the file (assuming that these environment variables
564 have been set). <P>
565 <LI> If the environment variable LD_LIBRARY_PATH (in the case of UNIX)
566 or PATH (in the case of Win32) contains the path to the shared object
567 files or dll, then the config file can be further simplified. Instead
568 of specifying a path to the shared object or dll, only the
569 name of the shared object or dll would suffice. That is, the Service
570 Configurator makes use of LD_LIBRARY_PATH (on UNIX) or PATH (on Win32)
571 to look for the shared object files or dlls.
572 </UL>
575 <P><HR><P>
579 The Server Logging Service provides a concurrent, multi-service daemon
580 that processes logging records received from one or more client hosts
581 simultaneously. The object-oriented design of the Server Logging
582 Service is decomposed into several modular components that perform
583 well-defined tasks. <P>
585 The following are the key classes in the Server Logging Service: <P>
586 <UL>
588 The Server_Logging_Handler class is a parameterized type that is
589 responsible for processing logging records sent to the Server from
590 participating client hosts. When logging records arrive from the
591 client host associated with a particular Logging Handler object, the
592 handle_input() method of the Server_Logging_Handler class is called
593 which in turn formats and displays the records on one or more output
594 devices (such as the printer, persistent storage, and/or console
595 devices. <P>
598 The class Server_Logging_Acceptor allocates in its handle_input()
599 routine a new instance of class Server_Logging_Handler on the heap,
600 and accepts connections into this Server_Logging_Handler. <P>
601 </UL>
603 The following describes how to configure the Logging Server:<P>
604 <UL>
607 The only parameter that the Logging Server takes is a listen
608 port number. You can specify a port number by passing a "-p
609 <port_number>" to the application. This can be done via the
610 svc.conf file.<P>
614 Here is an example svc.conf entry that dynamically loads the
615 Logging Server specifying port number to listen on for client
616 connections:<P>
618 <PRE> <CODE>
619 dynamic Server_Logging_Service Service_Object *
620 ../lib/netsvcs:_make_ACE_Server_Logging_Acceptor()
621 "-p 10202"
622 </PRE></CODE>
623 <P>
624 </UL>
625 Note:<P>
626 <UL>
627 <LI> These files would vary if the services are run on NT. For
628 example, instead of using *.so, we would have to use *.dll.<P>
629 <LI> Values for parameters can also be passed in using environment
630 variables. For example, instead of specifying absolute hostname or
631 port numbers in the config file, we can use $HOST and $PORT,
632 respectively, in the file (assuming that these environment variables
633 have been set). <P>
634 <LI> If the environment variable LD_LIBRARY_PATH (in the case of UNIX)
635 or PATH (in the case of Win32) contains the path to the shared object
636 files or dll, then the config file can be further simplified. Instead
637 of specifying a path to the shared object or dll, only the
638 name of the shared object or dll would suffice. That is, the Service
639 Configurator makes use of LD_LIBRARY_PATH (on UNIX) or PATH (on Win32)
640 to look for the shared object files or dlls.
641 </UL>
643 <P><HR><P>
647 The Client Logging Service multiplexes messages received from
648 different applications to the Server Logging Daemon running on a
649 designated host in a network/internetwork.
652 The following are the key classes in the Client Logging Service: <P>
653 <UL>
655 The Client_Logging_Handler class is a parameterized type that is
656 responsible for setting up a named pipe and using it to communicate
657 with different user processes on the same host. Once logging records
658 arrive from these processes, the handler reads these records in
659 priority order, performs network-byte order conversions on
660 multiple-header fields, and then transmits these records to the Server
661 Logging daemon across the network. <P>
664 The class Client_Logging_Connector connects to the Server Logging
665 daemon and then in its handle_input() routine it allocates a new
666 instance of the Client_Logging_Handler on the heap. <P>
667 </UL>
669 The following describes how to configure the Logging Client:<P>
670 <UL>
673 Configuring a Logging Client requires specifying all or some of the
674 following parameters. These parameters can be passed in to main
675 through command line as follows:<P>
680 </TD>
683 </TD>
686 </TD>
687 <TR>
690 </TD>
692 Hostname of the Server Logging Daemon <BR>
693 </TD>
695 ACE_DEFAULT_SERVER_HOST
696 </TD>
697 <TR>
700 </TD>
702 Port number of the Server Logging Daemon <BR>
703 </TD>
705 ACE_DEFAULT_LOGGING_SERVER_PORT
706 </TD>
707 <TR>
710 </TD>
712 Rendezvous key used to create named pipe
713 </TD>
715 ACE_DEFAULT_RENDEZVOUS
716 </TD>
717 </TABLE>
718 <P>
722 Here is an example svc.conf entry that dynamically loads the
723 Logging Client specifying host name and port number of the
724 Logging Server: <P>
726 <PRE> <CODE>
727 dynamic Client_Logging_Service Service_Object *
728 ../lib/netsvcs:_make_ACE_Client_Logging_Connector()
729 "-h tango.cs.wustl.edu -p 10202"
730 </PRE></CODE>
731 <P>
732 </UL>
733 Note:<P>
734 <UL>
735 <LI> These files would vary if the services are run on NT. For
736 example, instead of using *.so, we would have to use *.dll.<P>
737 <LI> Values for parameters can also be passed in using environment
738 variables. For example, instead of specifying absolute hostname or
739 port numbers in the config file, we can use $HOST and $PORT,
740 respectively, in the file (assuming that these environment variables
741 have been set). <P>
742 <LI> If the environment variable LD_LIBRARY_PATH (in the case of UNIX)
743 or PATH (in the case of Win32) contains the path to the shared object
744 files or dll, then the config file can be further simplified. Instead
745 of specifying a path to the shared object or dll, only the
746 name of the shared object or dll would suffice. That is, the Service
747 Configurator makes use of LD_LIBRARY_PATH (on UNIX) or PATH (on Win32)
748 to look for the shared object files or dlls.
749 </UL>
751 <P><HR><P>
755 The Logging Strategy Service can be used to control the output of all the
756 network services. It can be invoked with certain flags that determine
757 where the output of all the services should go. The Logging Strategy
758 Service sets the flags in ACE_Log_Msg, which controls all the streams
759 through macros such as ACE_DEBUG, ACE_ERROR, and ACE_ERROR_RETURN. If
760 default behavior is required, the Logging Strategy Service need not be
761 invoked or it can be invoked with no parameters. <P>
763 The following describes how to configure the Logging Strategy
764 Service:<p>
766 <UL>
769 Here are the command line arguments that can be given to the Logging
770 Strategy Service: <P>
774 where a flag can be any of the following: <P>
779 </TD>
782 </TD>
783 <TR>
785 STDERR <BR>
786 </TD>
788 Write messages to stderr. <BR>
789 </TD>
790 <TR>
792 LOGGER <BR>
793 </TD>
795 Write messages to the local client logger deamon. <BR>
796 </TD>
797 <TR>
799 OSTREAM <BR>
800 </TD>
802 Write messages to the ostream that gets created by specifying a
803 filename (see below) <BR>
804 </TD>
805 <TR>
807 VERBOSE <BR>
808 </TD>
810 Display messages in a verbose manner <BR>
811 </TD>
812 <TR>
814 SILENT <BR>
815 </TD>
817 Do not print messages at all <BR>
818 </TD>
820 </TABLE>
821 <P>
823 Note: If more than one flag is specified, the flags need to be 'OR'ed
824 as above syntax shows. Make sure there is no space in between the flag
825 and '|'. <P>
827 -s filename
828 <P>
830 If the OSTREAM flag is set, this can be used to specify the filename
831 where the output should be directed. Note that if the OSTREAM flag is
832 set and no filename is specified, ACE_DEFAULT_LOGFILE will be used to
833 write the output to. <P>
836 Here is an example svc.conf entry that dynamically loads the
837 Logging Strategy Service specifying that the output be sent
838 to STDERR: <P>
840 <PRE> <CODE>
841 dynamic Logging_Strategy_Service Service_Object *
842 ../lib/netsvcs:_make_ACE_Logging_Strategy()
843 "-f STDERR"
844 </PRE></CODE>
845 <P>
846 <OL>
848 "-f STDERR"
849 <P>
852 command line arguments as: <P>
853 "-f STDERR|OSTREAM -s mylog"
854 </OL>
855 Note:<P>
856 <UL>
857 <LI> These files would vary if the services are run on NT. For
858 example, instead of using *.so, we would have to use *.dll.<P>
859 <LI> Values for parameters can also be passed in using environment
860 variables. For example, instead of specifying absolute hostname or
861 port numbers in the config file, we can use $HOST and $PORT,
862 respectively, in the file (assuming that these environment variables
863 have been set). <P>
864 <LI> If the environment variable LD_LIBRARY_PATH (in the case of UNIX)
865 or PATH (in the case of Win32) contains the path to the shared object
866 files or dll, then the config file can be further simplified. Instead
867 of specifying a path to the shared object or dll, only the
868 name of the shared object or dll would suffice. That is, the Service
869 Configurator makes use of LD_LIBRARY_PATH (on UNIX) or PATH (on Win32)
870 to look for the shared object files or dlls.
871 </UL>
872 </UL>
874 <P><HR><P>
876 ACE</A> home page.
877 <!--#include virtual="/~schmidt/cgi-sig.html" -->
878 </BODY>
879 </HTML>