NAME
          cthread_publish - propogation of global information in
          cthreads

     LIBRARY
          C Threads Library (libcthreads.a)

     SYNOPSIS
          #include <cthread.h>

          int cthread_publish( void **p);

     PARAMETERS
          p      The address of a static global pointer variable.

     DESCRIPTION
          cthread_publish() is a convenience routine that helps to
          circumvent the vagaries of the memory model that cthreads
          presents on SPARCs and the BBN Butterfly.  As is explained
          in cthread_intro(3), on many target architectures, the
          cthreads memory model is such that "global" variables in C
          are not shared.  Only memory returned by memory_alloc(3) is
          shared and each processor has its own copy of the C "glo-
          bals".  The function of cthread_publish() is to copy the
          value of one of these C "global" variables and store it into
          the same variable on all the other processors.

          This is useful in the following way:  If you wanted to
          create a structure to contain information to be known to all
          processors you should,

          1)     use memory_alloc() to get shared memory for the
                 structure,

          2)     store the pointer returned by memory_alloc() in a C
                 "global" pointer variable,

          3)     call cthread_publish() passing as a parameter the
                 address of the global pointer variable.

          If, for example, that global pointer was named "gptr",
          cthread_publish(&gptr) would ensure that each processor's
          copy of gptr pointed to the same piece of memory.  Note that
          cthread_publish() does not in any way change the nature of
          gptr.  Each processor still has its own copy.  The thing
          they point to is shared, but the pointers themselves are
          still disjoint.



     EXAMPLE
          #include <cthread.h>
          /* typedef of structure to be shared */
          typedef struct shared_str {
               int count;
               mutex_t lock;
          } *shared_ptr_t;

          /* gptr is a C static global.  Disjoint copies may exist on
             all processors. */
          shared_ptr_t gptr;

          void worker();

          void
          init()
          {
               RESULT result;

               /* memory_alloc returns memory in shared area */
               result = memory_alloc(&gptr, sizeof(struct shared_str),
                              N_ANYWHERE);
               if (result != T_SUCCEED) {
                    cthread_perror("malloc failed!", result);
                    exit(1);
               }

               /* make sure all copies of gptr point to the
                  memory returned by the memory_alloc above */
               cthread_publish(&gptr);

               /* mutex pointer is in shared memory, not static.
                  No need to publish */
               result = mutex_alloc(&(gptr->lock), N_ANYWHERE);
               if (result != T_SUCCEED) {
                    cthread_perror("mutex_alloc failed!", result);
                    exit(1);
               }
               gptr->count = 0;

               cthread_detach(cthread_fork(worker, 1, 1));
               cthread_detach(cthread_fork(worker, 2, 2));

               barrier();
               printf("final count is %d0, gptr->count);
          }

          void
          worker(id)
          int id;
          {
               mutex_lock(gptr->lock);
               gptr->count++;
               mutex_unlock(gptr->lock);

          }

          main()
          {
               cthread_init(3, init);
          }

     SEE ALSO
          cthread_intro(3), memory_alloc(3)

     AUTHOR
          Cthreads was written and maintained by many people.
          This man page written by Greg Eisenhauer.