========>
========> Coffee Sample Application 
========>

(Coffee2.vbp, CoffWat2.vbp, MTCoffee.vbp, XTimers.vbp)

NOTE: Select Word Wrap from the Edit menu for easier viewing.
 
Coffee consists of a client, CoffWat2, and two ActiveX components (OLE servers), Coffee2 and MTCoffee. Together, these three projects demonstrate:

· Asynchronous notifications using events (Coffee2).
· Asynchronous notifications using call-back methods (Coffee2).
· Multithreading (MTCoffee).

XTimers.vbp is a helper project that provides a code-only timer used by Coffee2 and MTCoffee.

This is an expanded version of the project developed in the step-by-step procedures in Chapter 3, "Creating an ActiveX Exe Component," of Creating ActiveX Components. For more information on asynchronous notifications and multithreading, see Chapter 8, "Building Code Components."

File	        Description

CoffWat2.vbp	The CoffeeWatch client project.
CWMod1.bas	Startup code for the project.
CWForm1.frm	The client’s main form.
ICoffNot.cls	The ICoffeeNotify interface
		used for call-back methods.
CWNotMe.cls	NotifyMe object implements the
		ICoffeeNotify interface, so it
		can receive call-backs.
CWThread.frm	Client form for demonstrating 
		multithreading.
CWCofTrk.cls	The CoffeeTracker object used 
		to wait for completion events 
		from the multithreaded Coffee 
		object.
Coffee2.vbp	The Coffee2 component project.
Co2Cmon.cls	The CoffeeMonitor class used 
		to demonstrate asynchronous 
		notifications using events.
Co2Conn.cls	The Connector class that lets
		multiple clients share a 
		CoffeeMonitor object.
Co2CMon2.cls	The CoffeeMonitor2 class used 
		to demonstrate asynchronous 
		notifications using call-back 
		methods.
Co2Conn2.cls	The Connector2 class that lets
		multiple clients to share a 
		CoffeeMonitor2 object.
Co2Mod1.bas	Holds a reference to the 
		shared CoffeeMonitor and 
		CoffeeMonitor2 objects.
MTCoffee.vbp	The MTCoffee component 
		project.
MTCoffee.cls	The multithreaded Coffee 
		object.
MTCMod1.bas	A standard module for 
		demonstrating instancing of 
		global data.
XTimers.vbp	The call-back timer project.
XTimer.cls	XTimer object.
XTimerS.bas	Support module for XTimer.
AboutCof.txt	This document.

To Run

Although there's not a lot of code in it, this is a complex sample to run, because it demonstrates out-of-process components. For debugging, an out-of-process component must be run in a separate copy of Visual Basic.

In addition, the sample demonstrates features (multithreading and code-only timers) that either cannot be demonstrated in, or are dangerous to run in, the development environment.

1. Load XTimers.vbp into Visual Basic. On the File menu, select Make XTimers.dll to make the project into a .dll file.

IMPORTANT:  DO NOT run XTimers in the development environment at this time. XTimers must be compiled because it uses Windows APIs for a code-only timer object.

2. Load MTCoffee into Visual Basic. On the Project menu, select References to open the References dialog box. Select XTimers and click OK, to set a reference to the compiled DLL.

3. On the File menu, select Make MTCoffee.exe to make the project into an .exe file.

IMPORTANT: DO NOT run MTCoffee in the development environment at this time. You need to make the project because the development environment can’t support multiple threads of execution; if you run MTCoffee within Visual Basic, it won’t display multithreading behavior.

4. Load Coffee2.vbp into Visual Basic. On the Project menu, select References to open the References dialog box. Select XTimers and click OK, to set a reference to the compiled DLL.

5. Press CRTL+F5 to run the Coffee2 project.

Use CRTL+F5 instead F5 of when running an out-of-process component project, to ensure that all compile errors are caught before the component is supplying objects to the client. (See "Creating an ActiveX Exe Component," in Books Online.)

6. Start another instance of Visual Basic, and load CoffWat2.vbp. On the Project menu, select References to open the References dialog box. Select Coffee2 and MTCoffee, and then click OK, to set references to the running Coffee2 project and the compiled MTCoffee.EXE.

7. Press F5 to run the project.
 
After running the sample application and observing the behavior of MTCoffee when it allocates a separate thread for each Coffee object, you may find it instructive to recompile MTCoffee after changing the threading to a round-robin thread pool. (You can find this option in the Unattended Execution box, on the General tab of the Project Properties dialog box.) When using a round-robin thread pool, you can observe blocking and global data sharing between objects on the same thread.

You can also compile Coffee2.exe and CoffWat2.exe, and run multiple clients to observe sharing of the asynchronous notification objects CoffeeMonitor and CoffeeMonitor2.

With multiple clients, the round-robin thread pool means blocking and data sharing between Coffee objects in use by different clients.

To understand what's going on in this sample, see "Building Code Components," in Creating ActiveX Components in Books Online.

To add documents like this to Visual Basic projects, check "Add as Related Document" on the Add File dialog box.