6. Initialization

Before calling any other GM function, gm_init() should be called. gm_finalize() should be called after all other GM calls and before your program exits. Each call to gm_init() should be balanced by a call to gm_finalize() before the program exits. Although GM automatically handles ungraceful program termination without such balanced calls on operating systems with memory protection, developers are strongly discouraged from relying on this feature because on some systems, such as those using the VxWorks embedded runtime system, the calls to gm_finalize() are required for proper shutdown of GM to allow ports to be reused without rebooting VxWorks.

A GM port is initialized by calling gm_open(struct gm_port**port, unsigned int unit, unsigned int port_id, char *port_name, enum gm_api_version version) to open port number port_id of Myrinet interface number unit. The pointer returned at *port must be passed to subsequent GM API calls. port_name is an character string of up to gm_max_port_name_length() bytes describing the client. The name is currently used for debugging purposes only, but this information will eventually be available to all GM clients on the network through a mechanism TBD. version should be GM_API_VERSION_1_1.

Note that while the GM API uses "struct gm_port *" pointers throughout, these pointers are opaque to the client. The client should not attempt to dereference these pointers.

After opening a port, the client implicitly possesses gm_num_send_tokens() send tokens and gm_num_receive_tokens() receive tokens. Most GM programs will use most or all of the gm_num_receive_tokens() immediately after opening a port to pass receive buffers to GM using gm_provide_receive_buffer().

After the client has provided all receive buffers that it will provide during port initialization, the client should call gm_set_acceptable_sizes() for each priority (GM_LOW_PRIORITY and GM_HIGH_PRIORITY) to indicate what GM receive sizes the client expects to receive on the port. While this call is not strictly required, calling it allows GM to immediately reject any contradictory sends, immediately generating a send error at the sender. If these calls to gm_set_acceptable_sizes() are not made, then the error will not be reported until the sender experiences a GM long-period timeout, which takes about a minute to be generated by default. Therefore, calling gm_set_acceptable_sizes() can save much time during application development.