9.6. Documentation of the wxchat and Chat Server Programs

See also

• An overall discussion of the design of the chat client and server programs along with the Python module requirements and links to download the programs are found in the previous two sections. (Programming Assignment 5 – Add BRB feature to Multi-threaded Chat Server, A Multi-threaded Chat Server)
• Links to demonstation videos of using the chat server and clinet and also code walk throughs is found under Demonstration Videos.

9.6.1. Screen Shots of the wxchat Client Program

Here is a short description of how to use the wxchat program along with screen shots from the program.

When the program is first loaded, the user sees a Server pull down menu at the top and two buttons at the bottom of the window.

If the server is running on localhost or the user specified a server name on the command line when wxchat was started, they are ready connect to the server.

The Server pull down menu can be used to set or change the host name of the server.

Once the chat client knows how to find the server, the user may click on Connect and begin talking to whom ever is also connected to the server. They can set the name that they want to go by while chatting by entering a name and cliking on the Set Nick Name button. To send a message, they just type the message in the lower text window and either press the Enter key or click on the send button.

Messages that the user has typed appear in the middle window and messages received from the server appear in the upper window.

If the user needs to step away for a short time, they can click on the Be Right Back button. Entering a message before clicking on Be Right Back is optional.

No messages are sent to the client while they are away and the buttons change to indicate their status as being away.

After they have returned, they click on the I’m Back button to resume the chat session. Typing a message to go with I’m Back is optional.

This is an example of what another user will see when someone else is away and later returns.

9.6.2. Documentation of the wxchat Client Program

Here is a little bit of documentation about the more important functions and classes from the wxchat program. This documentation is auto-generated from the Python source code and doc strings contained in the source code.

File: wxchat.py

The client application (with GUI) to go along with the chat server. wxchat Requires wxPython.

Copyright 2009, Tim Bower: Apache Open Source License

class wxchat.ChatFrame(parent, id, title)

The main class containing the wxPython graphical interface.

OnExit(event)

Close the application by Destroying the object

add_readWin(msg)

Add text to the reading window

add_writeWin(msg)

Add text to the writing window

brb(event)

Be Right Back and I’m Back button call back

chatDisplay(msg)

Message to display from the chat server. Invoked via wx.CallAfter() in rendezvous.

clear_readWin()

Clear the reading widow

clear_writeWin()

Clear the writing window

connect(event)

Button call back, may be either Connect or Disconnect (same button)

connected()

Now connected to the Chat server Invoked via wx.CallAfter() in rendezvous.

getText()

Read text in from user

lostConnection(msg)

” We lost our connection to the chat server Invoked via wx.CallAfter() in rendezvous.

nickName(event)

Set Nick Name button call back

quit(event)

Quit button call back

resetServer(event)

Menu item call back

send(event)

Send button (and return key) event call back

setServer(event)

Menu item call back

File: rendezvous.py

A couple functions in a class just to facilitate communication between the networking thread and the main thread which does the graphics. Basically, the only purpose of these functions is so that the code that does the networking does not have to know anything about how the graphics are done (wx, TK, ...). Having this in a separate file also helps with imports so that there is not an import loop between the graphics and networking.

When used with wxPython, We just use the wx.CallAfter() function to send data from the networking thread to the wxFrame in the main thread.

If used with TKinter graphics (a previous implementation), we have to use a queue and generate new events on our own – much more complicated.

class rendezvous.Rendezvous(wxConnected, wxDisplay, wxLost)

Messages from the networking thread get left here and the appropriate wxPython events are generated to notify and pass data to the graphics thread.

connected()

Notify the main tread that we are connected to the server

display(msg)

shuttle a message to be displayed in the chat read window

lost(msg)

Notify the main tread that the network connection dropped

File: chatnetwork.py

The networking portion of chat room client. Most of this runs in a separate thread from the main thread which manages the graphical interface. See wxchat.py

Copyright 2009, Tim Bower. Apache Open Source License

class chatnetworking.ChatConnect(host, connected, display, lost)

Run as a separate thread to make and manage the socket connection to the chat server.

run()

The new thread starts here to listen for data from the server

send(msg)

Set up to send a message to the server - called from main thread This is the only part of this class that executes in the main tread, We use a list to drop off the message for the networking thread to pick up and actually send it. We could use a Queue.Queue object, which comes standard with Python and not have to mess with locks. When the graphics were done with Tkinter, I did that to send data back to the main thread. This locking stuff is pretty simple, so it’s a good place to see how to do the locking ourself.

9.6.3. Documentation of the Chat Server Program

Here is a little bit of documentation about the more important functions and classes from the chat server program. This documentation is auto-generated from the Python source code and doc strings contained in the source code.

File: chatserver.py

Chat Server with Threading

Copyright 2009, Tim Bower: Apache Open Source License

chatserverStub.mesg_index(old, last, new)

Parameters:

• old – integer index of oldest (first) message in queue
• last – integer index of last message read by the client thread
• new – integer index of newest (last) message in the queue

This computes the index value of the message queue from where the reader should return messages. It accounts for having a cyclic counter. This code is a little tricky because it has to catch all possible combinations.

class chatserverStub.MSGQueue

Manage a queue of messages for Chat, the threads will read and write to this object. This is an implementation of the readers - writers problem with a bounded buffer.

reader(lastread)

Reader of readers and writers algorithm

writer(data)

Writer of readers and writers algorithm

chatserverStub.sendAll(sock, lastread)

Get any unread messages and send them to the client

chatserverStub.clientExit(sock, peer, error=None)

Report that a client has exited the chat session.

chatserverStub.handlechild(clientsock)

The function that is ran as the thread to handle a client connection. It does the sending and receiving of data for one client

chatserverStub.main()

The parent thread that listens for connections and spawns a child thread to handle each connection.