Using the Active Containers Toolkit

To use the Active Containers toolkit, you must have the vipl.h and vip.lib files provided by your HW vendor.

Step-By-Step Instructions

  1. Install Toolkit
    1. Install AMVI (Complete instructions on Using AMVI webpage)
    2. Download and Unzip the AC Source Code (acsource.zip).
      For the remainder of instructions, assume the AC code is now in the AC_dir dirctory.
    3. Run nmake on:
      1. AC_dir/aclib.mak
      2. AC_dir/actest/amtest.mak
    4. To verify the setup:
      1. Start the name service by running ns_server/Debug/ns_server.exe in the AM directory.
      2. Start the test by running AC_dir/actest/Debug/actest.exe on both the server and the client. A description of actest is given below.

  2. Make Object Sharable
    1. Follow the instructions given below in Adding Container Functions to allow readers to get every type of update (insert, delete, etc).
    2. Every function arguement must implement the object interface which contains two virtual functions:
      1. OBJ_RETURN Marshall(MarshallStream* stream)
      2. OBJ_RETURN DeMarshall(DeMarshallStream* stream)
      For more details, please refer to the following source files:
      1. cstdCont.h
      2. MarshallStream.h, MarshallStream.cpp
      3. DeMarshallStream.h, DeMarshallStream.cpp
    3. Every shared data structure must implement the cStdCont interface which includes the virtual functions:
      1. bool Insert(Object* key, Object* obj)
      2. bool Delete(Object* key)
      3. bool MakeObjs(int func, Object** arg1, Object** arg2) which creates empty structures to be filled out when demarshalling an update.
      4. OBJ_RETURN Marshall(MarshallStream* stream)
      5. OBJ_RETURN DeMarshall(DeMarshallStream* stream)
      The inteface is given in cstdCont.h.

  3. Create/Use Writer Active Containers
    1. Create a writer using cS_Factory CreateWriter function.
    2. Any updating function calls should be made to the writer instead of directly accessing the shared data structure.
    3. A writer may be removed using the DeleteWriter function in the cS_Factory class.
    4. Please refer to actest.cpp for sample code.

  4. Create/Use Reader Active Containers
    1. Create a reader using cS_Factory CreateReader function.
    2. Readers should access the shared structure by calling the Readers GetCont function.
    3. A reader may be removed using the DeleteReader function in the cS_Factory class.
    4. Please refer to actest.cpp for sample code.

Adding Container Functions
Since the Active Container toolkit uses function shipping to update the readers, the containers must be able to process each function call. The distributed version of the toolkit currently supports insert (with 2 function arguements), delete (with 1 function arguement), and clear (with no function arguements). To add a function to the set of supported calls, you must:

  1. Add the new function declaration in cstdCont.h.
  2. Add a define so that the new function can be referenced by a unique integer. This should be done in sharedDefs.h.
  3. Add the new function in cS_Reader.cpp. The body of this function should simply call the original structure's corresponding function.
  4. The _ProcessCommands() function in cS_Reader.cpp should check for the integer corresponding to the new function and, if found, should call the reader's new function.
  5. Add the new function in cS_Writer.cpp. The body of this function should call the original structure's corresponding function and then call _SendUpdate with the function integer defined in step 2.

Description of ACTest
ACTest creates a grid where each block in the grid has a color and a value. The server fills a writer container with the grid values and colors. The writer container automatically propogates each update to the clients' reader active containers. The clients continuously read from their reader active containers and redraw the grid. As long as the readers are receiving the updates in a timely fashion the AC code is functioning properly. For the test's source code, please refer to the ACTest Source Code section of the Source Code for the Active Containers Toolkit webpage.

Back to Main Page
Website created by: Ted Bonkenburg ( tb@cs.cornell.edu ) and Vicky Weissman ( vickyw@cs.cornell.edu )