doc/doxygen/module-surf.doc

   1 /** @defgroup SURF_build_api Create a new API
   2     @ingroup SURF_API
   3     @brief How to build a new API on top of SURF
   4
   5     SURF provides the functionalities to simulate the platform. There are two main data types in SURF:
   6     the actions and the resources. Several types of resources exist:
   7         - the host resource,
   8         - the network resource,
   9         - the CPU resource,
  10         - the timer resource.
  11
  12     The implementation of these resources depends on the platform
  13     models you choose.  You can select your model by calling
  14     #surf_host_model_init_current_default() (which will give you a
  15     CLM03 model), or similar (see @ref SURF_models).
  16
  17     To initialize SURF, call
  18     #surf_host_model_init_current_default() or #surf_host_model_init_ptask_L07()
  19     to create the platform.
  20
  21     Then you can access the hosts with the @ref simgrid::s4u::Engine::get_all_hosts.
  22     Some functions of the @ref SURF_host_interface and similar can give
  23     you some information about:
  24         - a host: get_speed(), get_available_speed();
  25         - a network link: get_link_name(), get_link_latency(), get_link_bandwidth();
  26         - a route: get_route(), get_route_size().
  27
  28     During the simulation, call @a surf_host_model->execute() to schedule a
  29     computation task on a host, or @a surf_host_model->communicate()
  30     to schedule a communication task between two hosts. You can also create parallel task
  31     with @a surf_host_model->extension_public->execute_parallel_task(). These functions return
  32     a new action that represents the task you have just created.
  33
  34     To execute the actions created with @a execute(), @a communicate() or @a execute_parallel_task(), call
  35     EngineImpl::solve(). This function is where the simulation takes place. It returns the
  36     time elapsed to execute the actions. You can know what actions have changed their state thanks
  37     to the states sets. For example, if your want to know what actions are finished,
  38     extract them from @a surf_host_model->common_public->states.done_action_set.
  39     Depending on these results, you can schedule other tasks and call solve() again.
  40
  41     Have a look at the implementation of @ref MSG_API "MSG" and @ref SD_API "Simdag" to see how these module
  42     interact with SURF. But if you want to create a new API on top of SURF,
  43     we strongly recommend you to contact us before anyway.
  44
  45 */
  46