Matlab.h

/*
 * Medical Image Registration ToolKit (MIRTK)
 *
 * Copyright 2013-2015 Imperial College London
 * Copyright 2013-2015 Andreas Schuh
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef MIRTK_Matlab_H
#define MIRTK_Matlab_H

// Disable "Private field 'dependency' is not used" warning
#if defined __clang__
  #pragma clang diagnostic push
  #pragma clang diagnostic ignored "-Wunused-private-field"
#endif
// Include MATLAB Compiler Runtime header
#include <mclmcrrt.h>
// Enable warnings again
#if defined __clang__
  #pragma clang diagnostic pop
#endif


namespace mirtk {


/**
 * Interface to MATLAB Compiler Runtime (MCR)
 *
 * The static Matlab::Initialize or Matlab::InitializeApplication
 * functions should be called before any code that either makes use of the
 * MCR C++ functions or code generated by the MATLAB Compiler, respectively.
 * Only the first invocation of these functions will execute the MCR
 * initialization code. This is to ensure that the MCR was initialized.
 * Usually this initialization should take place at the begin of the main
 * function already, after the parsing of the command-line options.
 *
 * Code that makes use of the MATLAB C++ types and functions should include
 * the MCR proxy header file instead of the C++ header files shipped with
 * MATLAB itself. This guarantees that users only need an installation of the
 * free MCR to execute the code. Note that mclmcrrt.h is included by
 * mirtkMatlab.h and that it is recommended to include mirtkMatlab.h instead.
 *
 * @code
 * #include "mirtk/Matlab.h"
 *
 * int main(int argc, char *argv[]) {
 *   // Either load MCR libraries and environment only
 *   mirtk::Matlab::Initialize();
 *   // or initialize MCR completely
 *   mirtk::Matlab::InitializeApplication();
 *
 *   // [...] Use MATLAB types and functions
 *
 *   return 0;
 * }
 * @endcode
 */
class Matlab
{
  // ---------------------------------------------------------------------------
  // Attributes
private:

  /// Singleton object, auto-terminates MCR application when destructed
  static Matlab _Instance;

  /// Whether the MCR libraries are loaded and the environment is initialized
  static bool _McrInitialized;

  /// Whether the MCR application is initialized
  static bool _AppInitialized;

  // ---------------------------------------------------------------------------
  // Construction/destruction
private:

  /// Singleton object constructor
  Matlab();

  /// Terminates MCR application if it was initialized during program execution
  ~Matlab();

public:

  /// Get static singleton object
  static Matlab &Instance();

  // ---------------------------------------------------------------------------
  // Initialization

  /// Load MATLAT Compiler Runtime libraries and set environment
  ///
  /// Loads three main libraries (libmex, libmat, libmclmcr) and sets runtime
  /// environment for running MATLAB functions.
  ///
  /// Use InitializeApplication to initialize a standalone MCR application,
  /// which will also call mclmcrInitialize. This function may be used if
  /// mclInitializeApplication is not required, e.g., when only using some
  /// of MATLAB's C++ types and functions such as to read/write a MAT file.
  /// If code generated from .m files using the MATLAB Compiler is called,
  /// use InitializeApplication instead. If the MCR application uses a mclRunMain
  /// function, however, call Initialize first in the main function and then
  /// InitializeApplication in the mclRunMain function.
  ///
  /// This static function can be called at any time by the main thread before
  /// the execution of any MATLAB Compiler generated code. It will only
  /// initialize the MCR upon the first invocation.
  ///
  /// @sa mclmrcInitialize
  /// @sa http://uk.mathworks.com/matlabcentral/newsreader/view_thread/240279
  static void Initialize();

  /// Initialize MATLAB Compiler Runtime
  ///
  /// This function must be called before any of the code generated from .m
  /// files using the MATLAB Compiler is executed. It calls the MCR function
  /// mclInitializeApplication which implicitly loads the MCR libraries,
  /// and throws an error if this function failed.
  ///
  /// The MCR application is terminated automatically by the destructor of the
  /// static singleton object, i.e., mclTerminateApplication must not be called
  /// explicitly by the user.
  ///
  /// This static function can be called at any time by the main thread before
  /// the execution of any MATLAB Compiler generated code. It will only
  /// initialize the MCR upon the first invocation.
  ///
  /// @sa mclmrcInitialize
  /// @sa mclInitializeApplication
  /// @sa http://uk.mathworks.com/matlabcentral/newsreader/view_thread/240279
  static void InitializeApplication(const char **options, int count);

};


} // namespace mirtk

#endif // MIRTK_Matlab_H