MCA2 Programmer's Guide
Prev	Fast Backward	Chapter 5. How to use blackboards	Fast Forward	Next

5.2. Using already defined blackboards

After creation of a blackboard these can simply be used by calling the UseBlackboard function. It returns a pointer to an already existing blackboard. If the blackboard does not exist within the same part environment a blackboard copy is created. There is no difference in the use of a blackboard and a blackboard copy. But you have to keep in mind that a blackboard copy has to update its content via TCP from and to its original one.

Example 5-2. Use an already existing Blackboard

  tBlackboard *list_bb;
  tBlackboardInfo list_bbinfo("List",eBBT_CHAR_S, 10, (list_entry_max_length+1)*sizeof(signed char));
  list_bb=UseBlackboard(list_bbinfo);

The UseBlackboard is in most cases also used immediately after creation of the blackboard with AddBlackboard. Beside getting a pointer ro a blackboard structure the UseBlackboard also increments an internal counter of the blackboard. This is decremented within the ReleaseBlackboard. If the counter is decremented to 0, the blackboard is deleted, as then nobody wants to use it any longer.

After creation of use indication of a blackboard the blackboards content is of interest. As there may be multiple threads and processes accessing the blackboard, depending on the kind of access the blackboard has to be locked. There are read and write locks. Assuming that the considered blackboard is a blackboard copy, its content will be updated on a read lock. Doing a write lock will additionally update the original blackboard after releasing the blackboard copy. Between locking and releasing the original and all other copies are blocked, e.g. no other module is able to access to the blackboard.

Example 5-3. Write a blackboard element

Here's how to write to an element of a blackboard:

if (list_bb->Lock(Identification(this), eBB_READ_WRITE))
   {
     char *first_entry=list_bb->Element(0);
     strcpy(first_entry,"first entry\n");
     list_bb->Unlock(Identification(this));
   }
else
   {
     UINFO("lock not possible\n");
   }

Example 5-4. Read a blackboard element

And here's how to read the same element from another point.

if (list_bb->Lock(Identification(this), eBB_READ_LOCK))
   {
     char *first_entry=list_bb->Element(0);
     UINFO("first entry in blackboard is %s\n",first_entry);
     list_bb->Unlock(Identification(this));
   }
else
   {
     UINFO("lock not possible\n");
   }

Every element (entrie) of a blackboard has a separat counter, that is incrmented when the Element is accesed via the Element function within a write-lock block. Only if these counters of elements on original and copy side differ, transferring data is necessary in Lock and Unlock functions.

The lock functions accept an optional third parameter, that defines how long the Lock function has to wait before returning unsuccessful. If a zero time (the default) is given, it does not wait and return immediately of locking the blackboard is not possible at the moment. A negativ time indicates that the Lock function has to wait as long as necessary (forever, if another user does not call the Unlock function.