5 NBS Routines Listed by Category

In this section, routines are listed by category. For each routine there is a one-line description of what it does. There is a full alphabetical description of the routines in Appendix A.

5.1 NBS_TUNE — Routines used to alter global noticeboard system parameters

Two types of parameters can be altered. The first type is global to a process and not to a noticeboard (they are essentially Fortran COMMON block or C static variables). The second type is global to a noticeboard and are thus shared by all processes accessing that noticeboard. The original NBS_TUNE routine is used to alter parameters of the first type and the newer NBS_TUNE_NOTICEBOARD is used to tune parameters of the second type. When a noticeboard is created, its initial parameter values are copied from the current values of the first type.

When a parameter is altered, its previous value is returned and this permits a routine to alter a parameter, use the new value and then restore the parameter to its previous value.

The NBS_FIND, NBS_GET and NBS_PUT routines make rather complicated use of these values. For those parameters which are logical flags, they use the OR of the value of the first type and the value of the second type. For those parameters which are numeric values, they use the value of the first type.

5.2 NBS_DEFINITION — Routines used to define the noticeboard structure

A private memory area is obtained and item definitions are created in it. Storage is not allocated for data but nevertheless data pointers are defined as though the data began at address zero. These pointers are relocated at the time that the definition is either written to disc or else copied to a noticeboard.

5.3 NBS_FIND — Routines that find noticeboards and items within noticeboards

Items can be found either by name or by position. When a noticeboard is found a private copy of its item descriptors is made in which all non NIL pointers are relocated by the virtual address of the start of the relevant noticeboard. Thus, once a noticeboard has been found, all information pertaining to it can in fact be accessed using standard C structures.

5.4 NBS_LOSE — Routines that lose noticeboards and items within noticeboards

The noticeboard system maintains counts of how many items have been found using NBS_FIND_ITEM and NBS_FIND_NTH_ITEM. The routines in this section can be used to indicate that noticeboards and items are no longer required. When a noticeboard is no longer required, it is marked for deletion. When an item is no longer required, its parent’s item count is decremented. Normally, noticeboards and items can only be lost if the count of items found from them is zero (this is to minimise the chance of using an item ID to access a non-existent noticeboard), but this can be overridden.

5.5 NBS_PUT — Routines that write information to a noticeboard

This can normally only be done by the owner of the noticeboard. The only things which can be written are shape information and data. The item’s modified count is incremented both before and after each write using the ADD_INTERLOCKED instruction. The noticeboard’s modified count is incremented after each write. These modified counts allow other processes to monitor the noticeboard for changes.

When writing data to an item, it is possible to specify the offset at which the data is to start. The actual size of the item’s data is the high-water mark of all the data that has been written to the item. For example, if 10 bytes are written at offset 0, the size is 10 bytes, but if then 100 bytes are written at offset 4000, the size is 4100 bytes, even though bytes 11 to 4000 have not been written. It is guaranteed that all such unwritten bytes are zero. It is occasionally necessary to adjust the actual size of an item’s data and there is a routine explicitly to do this. For example, the size of the above item could be adjusted back to 10 bytes. Note that if 1 byte were now written at an offset of 10000, the item size would now be 10001 bytes and the 100 bytes at offset 4000 would retain the values that they were given earlier (they would not be reset to zero).

There are two global parameters which can be altered using the NBS_TUNE_NOTICEBOARD routine and which affect the behaviour of these routines:

1. WORLD_WRITE is FALSE by default and this prevents processes other than the noticeboard’s owner from writing to it. If set TRUE, this process will be allowed to write to the noticeboard even if it does not own it. If set TRUE then it is possible for a reader to read data that is currently varying, so only do this if you know what you are doing. All processes can always access all noticeboard’s directly if they do so via pointer — such access is not affected by the WORLD_WRITE flag.

2. INCREMENT_MODIFY is TRUE by default and this causes the item’s modified count to be incremented before and after the update and the noticeboard’s modified count to be incremented after the update. If set FALSE, neither count is altered. Clearly, if this is done, other processes monitoring the modified counts will not realise that noticeboard data is changing.

There is also a lower-level routine that must only be used by people who really know what they are doing. It increments either the noticeboard modified count or a primitive item’s modified count. This must be called according to the same conventions as are applied in NBS_PUT_VALUE. If this is not done, the whole system is subverted.

Finally, there is a routine which specifies a user-supplied routine to be called whenever an item’s shape, data, size or modified count is altered. This routine is called in the context of the process which alters the noticeboard — there are no facilities for notifying directly any other processes (although the user-supplied routine may of course do this itself).

5.6 NBS_GET — Routines that read information from a noticeboard

Normally this is a very straightforward operation, but when reading shape information and data it is necessary to check that the owner of the information has not altered it whilst it is being read.

There are three global parameters which can be altered using the NBS_TUNE_NOTICEBOARD routine and which affect the behaviour of the shape and data reading routines:

1. CHECK_MODIFY is TRUE by default and this means that the item’s modified count is checked both before and after reading the data. The data is read repeatedly until the value of this count is even and unchanging or until a timeout occurs. If set FALSE, no such checks are made and no timeout can occur.

2. TIMEOUT_COUNT is 100 by default and is the maximum number of times that the data reading will be tried.

3. TIMEOUT_INTERVAL is 100 by default and is the delay in milliseconds between tries.