Wrapper Facade
Total Page：16
File Type：pdf, Size：1020Kb
Wrapper Facade A Structural Pattern for Encapsulating Functions within Classes Douglas C. Schmidt [email protected] Department of Computer Science Washington University St. Louis, MO 63130, (314) 935-7538 This paper appeared in the C++ Report magazine, Febru- ary, 1999. CLIENT DATABASE 1 Introduction PRINTER CONNECTION This paper describes the Wrapper Facade pattern. The intent REQUEST LOGGING of this pattern is to encapsulate low-level functions and data SERVER structures with object-oriented (OO) class interfaces. Com- SOCKET HANDLES mon examples of the Wrapper Facade pattern are class li- NETWORK braries like MFC, ACE, and AWT that encapsulate native CONSOLE OS C APIs, such as sockets, pthreads, or GUI functions. CLIENT LOGGING Programming directly to native OS C APIs makes net- RECORDS LOGGING working applications verbose, non-robust, non-portable, and RECORDS hard to maintain because it exposes many low-level, error- CLIENT SERVER prone details to application developers. This paper illus- trates how the Wrapper Facade pattern can help to make these types of applications more concise, robust, portable, and maintainable. Figure 1: Distributed Logging Service This paper is organized as follows: Section 2 describes the Wrapper Facade pattern in detail using the Siemens for- mat [1] and Section 3 presents concluding remarks. The logging server shown in Figure 1 handles connec- tion requests and logging records sent by clients. Logging records and connection requests can arrive concurrently on 2 Wrapper Facade Pattern multiple socket handles. Each handle identifies network communication resources managed within an OS. 2.1 Intent Clients communicate with the logging server using a connection-oriented protocol like TCP [2]. Thus, when a Encapsulate low-level functions and data structures within client wants to log data, it must first send a connection re- more concise, robust, portable, and maintainable higher- quest to the logging server. The server accepts connection level object-oriented class interfaces. requests using a handle factory, which listens on a network address known to clients. When a connection request ar- 2.2 Example rives, the OS handle factory accepts the client’s connection and creates a socket handle that represents this client’s con- To illustrate the Wrapper Facade pattern, consider the server nection endpoint. This handle is returned to the logging for a distributed logging service shown in Figure 1. Client server, which waits for client logging requests to arrive on applications use the logging service to record information this and other socket handles. Once clients are connected, about their execution status in a distributed environment. they can send logging records to the server. The server re- This status information commonly includes error notifica- ceives these records via the connected socket handles, pro- tions, debugging traces, and performance diagnostics. Log- cesses the records, and writes them to their output device(s). ging records are sent to a central logging server, which writes A common way to develop a logging server that processes the records to various output devices, such as a network man- multiple clients concurrently is to use low-level C language agement console, a printer, or a database. functions and data structures for threading, synchronization 1 and network communication. For instance, Figure 2 illus- // Set up the address to become a server. trates the use of Solaris threads [3] and the socket [4] net- memset (reinterpret_cast <void *> (&sock_addr), work programming API to develop a multi-threaded logging 0, sizeof sock_addr); server. sock_addr.sin_family = AF_INET; sock_addr.sin_port = htons (logging_port); sock_addr.sin_addr.s_addr = htonl (INADDR_ANY); // Associate address with endpoint. SERVER LOGGING SERVER bind (acceptor, reinterpret_cast <struct sockaddr *> (&sock_addr), sizeof sock_addr); 1: socket() 2: bind() // Make endpoint listen for connections. 3: listen() listen (acceptor, 5); 8: recv() 8: recv() 5: accept() 9: write() 9: write() 6: thr_create() // Main server event loop. for (;;) { Logging Logging Logging thread_t t_id; Acceptor Handler Handler // Handle UNIX/Win32 portability differences. 4: connect() #if defined (_WINSOCKAPI_) 7: send() SOCKET h; #else 7: send() int h; CLIENT CLIENT #endif /* _WINSOCKAPI_ */ A NETWORK B // Block waiting for clients to connect. int h = accept (acceptor, 0, 0); // Spawn a new thread that runs the // <logging_handler> entry point and Figure 2: Multi-threaded Logging Server // processes client logging records on // socket handle <h>. thr_create (0, 0, In this design, the logging server’s handle factory accepts logging_handler, client network connections in its main thread. It then spawns reinterpret_cast <void *> (h), THR_DETACHED, a new thread that runs a logging handler function to &t_id); process logging records from each client in a separate con- } nection. The following two C functions illustrates how to /* NOTREACHED */ implement this logging server design using the native Solaris return 0; OS APIs for sockets, mutexes, and threads.1 } // At file scope. The logging handler function runs in a separate thread of control, i.e., one thread per connected client. It receives // Keep track of number of logging requests. static int request_count; and processes logging records on each connection, as fol- lows: // Lock to protect request_count. static mutex_t lock; // Entry point that processes logging records for // one client connection. // Forward declaration. void *logging_handler (void *arg) static void *logging_handler (void *); { // Handle UNIX/Win32 portability differences. // Port number to listen on for requests. #if defined (_WINSOCKAPI_) static const int logging_port = 10000; SOCKET h = reinterpret_cast <SOCKET> (arg); #else // Main driver function for the multi-threaded int h = reinterpret_cast <int> (arg); // logging server. Some error handling has been #endif /* _WINSOCKAPI_ */ // omitted to save space in the example. for (;;) { int UINT_32 len; // Ensure a 32-bit quantity. main (int argc, char *argv[]) char log_record[LOG_RECORD_MAX]; { struct sockaddr_in sock_addr; // The first <recv> reads the length // (stored as a 32-bit integer) of // Handle UNIX/Win32 portability differences. // adjacent logging record. This code #if defined (_WINSOCKAPI_) // does not handle "short-<recv>s". SOCKET acceptor; ssize_t n = recv #else (h, int acceptor; reinterpret_cast <char *> (&len), #endif /* _WINSOCKAPI_ */ sizeof len, 0); // Create a local endpoint of communication. // Bail out if we don’t get the expected len. if (n <= sizeof len) break; acceptor = socket (PF_INET, SOCK_STREAM, 0); len = ntohl (len); // Convert byte-ordering. if (len > LOG_RECORD_MAX) break; 1 Readers who are not interested in the complete code details of this ex- ample can skip to the pattern’s Context in Section 2.3. // The second <recv> then reads <len> 2 // bytes to obtain the actual record. across different versions of the same OS or compiler. Non- // This code handles "short-<recv>s". for (size_t nread = 0; portability stems from the lack of information hiding in low- nread < len; level APIs based on functions and data structures. nread += n) { For instance, the logging server implementation in Sec- n = recv (h, log_record + nread, tion 2.2 has hard-coded dependencies on several non- len - nread, 0); portable native OS threading and network programming C // Bail out if an error occurs. if (n <= 0) APIs. In particular, the use of thr create, mutex lock, return 0; and mutex unlock is not portable to non-Solaris OS plat- } forms. Likewise, certain socket features, such as the use of mutex_lock (&lock); int to represent a socket handle, are not portable to non- // Execute following two statements in a UNIX platforms like WinSock on Win32, which represent a // critical section to avoid race conditions socket handle as a pointer. // and scrambled output, respectively. ++request_count; // Count # of requests received. High maintenance effort: C and C++ developers typically if (write (1, log_record, len) == -1) achieve portability by explicitly adding conditional com- // Unexpected error occurred, bail out. pilation directives into their application source code using break; #ifdefs. However, using conditional compilation to ad- mutex_unlock (&lock); dress platform-specific variations at all points of use in- } creases the physical design complexity [6] of application close (h); source code. It is hard to maintain and extend such software return 0; since platform-specific implementation details are scattered } throughout the application source files. Note how all the threading, synchronization, and networking For instance, the #ifdefs that handle Win32 and UNIX code is programmed using the low-level C functions and data portability with respect to the data type of a socket, i.e., structures provided by the Solaris operating system. SOCKET vs. int, impedes the readability of the code. Developers who program to low-level C APIs like these 2.3 Context must have intimate knowledge of many OS platform idiosyn- crasies to write and maintain this code. Applications that access services provided by low-level func- As a result of these drawbacks, developing applications by tions and data structures. programming directly to low-level functions and data struc- tures is rarely an effective design choice for application soft- 2.4 Problem ware. Networking applications are often written using the low- level functions and data structures illustrated in Section 2.2. 2.5