C* PROGRAMMING GUIDE May 1993 Copyright (c) 1990-1993 Thinking Machines Corporation. CHAPTER 11: INTRODUCTION TO THE C* COMMUNICATION LIBRARY ******************************************************** Chapters 11-14 of this guide describe a set of C* library functions that provide different kinds of communication. For example, these functions allow you to: o Send values of parallel variable elements to other elements of the same shape. o Send values of parallel variable elements of one shape to elements of another shape. o Perform different kinds of computation on values while sending them to elements of the same or a different shape. o Send data from parallel variable elements to a scalar variable, and from a scalar variable to a parallel variable element. o Send data from a parallel variable to a scalar array, or from an array to a parallel variable. Of course, you can perform similar kinds of communication using features of C* itself; see Chapter 10. These library functions supplement, and in many cases overlap, the communication features contained in the language itself. Several of them are particularly useful when the rank of a shape is not known until run time; in that situation, you cannot use left indexing to specify a parallel variable element, because you cannot specify values for all the axes when you write the program. The functions, however, provide a way to manipulate such data. This chapter introduces the methods of communication available using C* library functions, and gives an overview of these functions. Include the header file in programs that call any of the functions discussed in the next three chapters. The functions are part of the C* run-time system, and are linked in to your program by default. 11.1 TWO KINDS OF COMMUNICATION -------------------------------- There are two different kinds of communication in C*: grid and general. 11.1.1 Grid Communication -------------------------- In grid communication, elements of parallel variables in the same shape communicate in regular patterns by using their coordinates. In other words, values of all elements in a parallel variable move the same number of positions in the same direction--for example, each element sends its value to the element of another parallel variable that is two coordinates higher along axis 0. These functions implement grid communication: o from_grid o from_grid_dim o from_torus o from_torus_dim o to_grid o to_grid_dim o to_torus o to_torus_dim In addition, the pcoord function, which we discussed in Chapter 10, can be used in certain kinds of grid communication. Grid communication is discussed in Chapter 12. 11.1.2 General Communication ----------------------------- General communication allows any parallel variable element to send its value to any other element, whether or not they are of the same shape, and whether or not the pattern of communication is regular. It also allows scalar variables to send values to or receive values from parallel variables. This kind of communication uses a position's send address rather than its coordinates. The send address is a combination of a position's shape and coordinates that uniquely identifies the position among all positions in all shapes. General communication is more versatile than grid communication, but it is also slower. It achieves the same result as parallel left-indexing a parallel variable; see Chapter 10. General communication is implemented by these C* functions: o make_send_address o send o get o read_from_position o read_from_pvar o write_to_position o write_to_pvar o make_multi_coord These functions are discussed in Chapter 14. 11.2 COMMUNICATION AND COMPUTATION ----------------------------------- Many C* functions perform computations or combining operations on the parallel values they transmit. Most of these functions involve grid communication. For example, the scan function lets you combine values of specified elements of a parallel variable along an axis of a shape. You can add these values, for example, multiply them, or take the minimum or maximum. These C* library functions provide communication and computation: o scan o spread o copy_spread o multispread o copy_multispread o enumerate o rank o reduce o copy_reduce o global These functions are discussed in Chapter 13. ----------------------------------------------------------------- Contents copyright (C) 1990-1993 by Thinking Machines Corporation. All rights reserved. This file contains documentation produced by Thinking Machines Corporation. Unauthorized duplication of this documentation is prohibited. ***************************************************************** The information in this document is subject to change without notice and should not be construed as a commitment by Think- ing Machines Corporation. Thinking Machines reserves the right to make changes to any product described herein. Although the information in this document has been reviewed and is believed to be reliable, Thinking Machines Corporation assumes no liability for errors in this document. Thinking Machines does not assume any liability arising from the application or use of any information or product described herein. ***************************************************************** Connection Machine (r) is a registered trademark of Thinking Machines Corporation. CM, CM-2, CM-200, and CM-5 are trademarks of Thinking Machines Corporation. C* (r) is a registered trademark of Thinking Machines Corporation. Thinking Machines (r) is a registered trademark of Thinking Machines Corporation. UNIX is a registered trademark of UNIX System Laboratories, Inc. Copyright (c) 1990-1993 by Thinking Machines Corporation. All rights reserved. Thinking Machines Corporation 245 First Street Cambridge, Massachusetts 02142-1264 (617) 234-1000