NAME

shared_domain -- communication domain based on shared memory

SYNOPSIS

   #include <afblib/shared_domain.h>

   struct shared_domain* sd_setup(size_t nbytes,
      unsigned int nofprocesses);
   struct shared_domain* sd_setup_with_extra_space(size_t nbytes,
      unsigned int nofprocesses, size_t extra_space_size);
   struct shared_domain* sd_connect(char* name, unsigned int rank);
   void sd_free(struct shared_domain* sd);

   unsigned int sd_get_rank(struct shared_domain* sd);
   unsigned int sd_get_nofprocesses(struct shared_domain* sd);
   char* sd_get_name(struct shared_domain* sd);
   size_t sd_get_extra_space_size(struct shared_domain* sd);
   void* sd_get_extra_space(struct shared_domain* sd);

   bool sd_barrier(struct shared_domain* sd);
   bool sd_write(struct shared_domain* sd, unsigned int recipient,
      const void* buf, size_t nbytes);
   bool sd_read(struct shared_domain* sd, void* buf, size_t nbytes);

DESCRIPTION

A shared communication domain allows nofprocesses processes to communicate and synchronize with each other using a shared memory segment.

A shared communication domain for nofprocesses processes is created by sd_setup. The internal per-process buffers have a size of nbytes each. Each shared communication domain is accessible to other processes belonging to the same user through a temporary file in /tmp whose name can be retrieved using sd_get_name. A shared communication domain can be released using sd_free. While sd_setup must be called by one process only, sd_free is to be called by all participating processes when access is no longer required.

sd_setup_with_extra_space works like sd_setup but allocates a shared memory segment with extra space of extra_space_size bytes. This extra space can be accessed through sd_get_extra_space and its size can be retrieved using sd_get_extra_space_size.

Other processes are free to connect to an already existing shared communication domain using sd_connect where the name and the rank (in the range of 0 to nofprocesses-1) are to be specified.

Communication among the processes of a shared communication domain is possible through sd_write and sd_read. Both functions block until the full amount has been written or read. Both operations work atomically even if the number of bytes exceeds that of the internal buffer size. This means that multiple write operations to the same process will never mix nor do concurrent read operations by one process (possible through multiple threads) interfere with each other.

sd_barrier provides a simple synchronization mechanism among all processes of a shared communication domain. Each process who calls sd_barrier is suspended until all processes have invoked sd_barrier.

AUTHOR

Andreas F. Borchert