dist_cnc.h

//********************************************************************************
// Copyright 2007-2010 Intel Corporation All Rights Reserved.                   **
//                                                                              **
// The source code contained or described herein and all documents related to   **
// the source code ("Material") are owned by Intel Corporation or its suppliers **
// or licensors. Title to the Material remains with Intel Corporation or its    **
// suppliers and licensors. The Material contains trade secrets and proprietary **
// and confidential information of Intel or its suppliers and licensors. The    **
// Material is protected by worldwide copyright and trade secret laws and       **
// treaty provisions. No part of the Material may be used, copied, reproduced,  **
// modified, published, uploaded, posted, transmitted, distributed, or          **
// disclosed in any way without Intel's prior express written permission.       **
//                                                                              **
// No license under any patent, copyright, trade secret or other intellectual   **
// property right is granted to or conferred upon you by disclosure or delivery **
// of the Materials, either expressly, by implication, inducement, estoppel or  **
// otherwise. Any license under such intellectual property rights must be       **
// express and approved by Intel in writing.                                    **
//********************************************************************************

// ===============================================================================
// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
//
//    INCLUDE THIS FILE ONLY TO MAKE YOUR PROGRAM READY FOR DISTRIBUTED CnC
//
// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
// ===============================================================================

#ifndef __DIST_CNC__H_
#define __DIST_CNC__H_

/// \page distcnc CnC for distributed memory (distCnC)
///
/// In principle, every clean CnC program should run with distCnC.
/// Most of the mechanics of data distribution etc. is handled inside
/// the runtime and the programmer does not need to bother about the
/// gory details. Of course, there are a few minor changes needed to
/// make a program distCnC-ready, but once that's done, it will run on
/// distributed CnC as well as on "normal" CnC (decided at runtime).
///
/// \section dc_comm Inter-process communication
/// Conceptually, distCnC allows data and computation distribution
/// across any kind of network; but currently only a socket-based
/// communication model is provided. Support for KNF or MPI might
/// follow.
///
/// \section dc_link Linking for distCnC
/// distCnC is part of the "normal" CnC distribution, e.g. it comes
/// with the necessary communication libraries (cnc_socket). The
/// communication library is loaded on demand at runtime, hence you do
/// not need to link against extra libraries to create distCnC-ready
/// application. Just link your binaries like a "tradiditional" CnC
/// application (explained in the CnC User Guide, which can be found
/// in the doc directory).
///
/// \section dc_prog Making your program distCnC-ready
/// As a distributed version of a CnC program needs to do things which
/// are not required in a shared memory version, the extra code for
/// distCnC is hidden from "normal" CnC headers. To include the
/// features required for a distributed version you need to
/// \code #include <cnc/dist_cnc.h> \endcode
/// instead of \code <cnc/cnc.h> \endcode .
/// If you want to be able to create optimized binaries for shared
/// memory and distributed memory from the same source, you might
/// consider protecting distCnC specifics like this:
///   @code
///    #ifdef _DIST_
///    # include <cnc/dist_cnc.h>
///    #else
///    # include <cnc/cnc.h>
///    #endif
///   @endcode
///
/// In "main", initialize an object CnC::dist_cnc_init< list-of-contexts >
/// before anything else; parameters should be all context-types ever
/// used in the program:
///   @code
///    #ifdef _DIST_
///        CnC::dist_cnc_init< my_context_type_1 /*, my_context_type_2, ... */ > _dinit;
///    #endif
///   @endcode
///
/// If and only if your items and/or tags are non-standard data types,
/// the compiler will notify you about the need for serialization
/// capability.  Serialization of structs/classes without pointers or
/// virtual functions can easily be enabled using
/// CNC_BITWISE_SERIALIZABLE( type ); others need a "serialize"
/// method or function. See \ref serialization for more details.
///
/// Step instances are distributed across clients and the host. By
/// default, they are distributed in a round-robin fashion. Note that
/// every process can put tags (and so prescribe new step instances).
/// The round-robin distribution decision is made locally on each
/// process (not globally).
///
/// If the same tag is put multiple times, it might be scheduled for
/// execution on different processes and the preserveTags attribute of
/// tag_collections will then not have the desired effect.
///
/// To potentially get around this problem, you can provide a tuner when
/// prescribing steps with a CnC::tag_collection. The tuner should be
/// derived from CnC::default_tuner and provide a method called
/// "pass_on", which takes the tag of the step and the context as
/// arguments and has to return the process number to run the step
/// on. To avoid the aforementioned problem, you simply need to make
/// sure that the return value is independent of the process it is
/// executed on. The pass_on mechanism can be used to provide any
/// distribution strategy which can be computed locally.
///
///   @code
///    struct my_tuner : public CnC::default_tuner< tag_type, context_type >
///    {
///        int pass_on( const tag_type & tag, context_type & ) const { return tag % 4; }
///    };
///   @endcode
///
///
/// \attention Pointers as tags are not yet supported by distCnC. It
/// should be possible to implement a serializable wrapper for
/// pointers, though.
///
/// \attention Global variables are evil and must not be used within
/// the execution scope of steps.
///
/// \attention "Global" attributes of collections
/// (e.g. size(), iteration, etc.) must not be used while steps are
/// being executed (e.g. within the dynamic scope of step-code).
///
/// \section dc_run Running with distCnC over sockets
/// On application start-up, CnC checks the environment variable
/// "CNC_SOCKET_HOST".  If it is set to a number, it will print a
/// contact string and wait for the given number of clients to
/// connect. Usually this means that clients need to be started
/// "manually" as follows: set "CNC_SOCKET_CLIENT" to the given
/// contact string and launch the same executable on the desired
/// machine.
///
/// If "CNC_SOCKET_HOST" is is not a number it is interpreted as a
/// name of a script. CnC executes the script twice: First with "-n"
/// it expects the script to return the number of clients it will
/// start. The second invocation is expected to launch the client
/// processes.
///
/// There is a sample script "misc/start.sh" which you can
/// use. Usually all you need is setting the number of clients and
/// replacing "localhost" with the names of the machines you want the
/// application(-clients) to be started on. It requires password-less
/// login via ssh. It also gives some details of the start-up
/// procedure. For windows, the script "start.bat" does the same,
/// except that it will start the clients on the same machine without
/// ssh or alike. Adjust the script to use your preferred remote login
/// mechanism.


#ifndef _DIST_CNC_
# define _DIST_CNC_
#endif

#include <cnc/internal/dist/dist_init.h>

namespace CnC {
    namespace Internal {
        class void_context;
    }

    /// To enable remote CnC you must create one such object right after entering main.
    /// The object must persist throughout main.
    /// All context classes ever used in the program must be referenced as template arguments.
    /// All contexts must have all collections they use as members and must be default-constructable.
    /// Pointers as tags are not supported by distCnC.
    template< class C1, class C2 = Internal::void_context, class C3 = Internal::void_context,
              class C4 = Internal::void_context, class C5 = Internal::void_context >
    struct /*CNC_API*/ dist_cnc_init : public Internal::dist_init< C1, C2, C3, C4, C5 >
    {
        dist_cnc_init() : Internal::dist_init< C1, C2, C3, C4, C5 >() {}
    };

} // namespace CnC

#include <cnc/cnc.h>

#endif // __DIST_CNC__H_