X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/49e2303ab8fb6ac8f8f7a0fbbaa73528256396a7..0bfafcab47ae9cd7856bd8d129404c33079d6afe:/examples/README.rst diff --git a/examples/README.rst b/examples/README.rst index 735ca8f79c..3937917972 100644 --- a/examples/README.rst +++ b/examples/README.rst @@ -11,7 +11,7 @@ SimGrid comes with an extensive set of examples, documented on this page. Most of them only demonstrate one single feature, with some larger examplars listed below. -The C++ examples can be found under examples/s4u while python examples +The C++ examples can be found under examples/cpp while python examples are in examples/python. Each such directory contains the source code (also listed from this page), and the so-called tesh file containing how to call the binary obtained by compiling this example and also the expected @@ -38,7 +38,7 @@ Starting and Stopping Actors .. tabs:: - .. example-tab:: examples/s4u/actor-create/s4u-actor-create.cpp + .. example-tab:: examples/cpp/actor-create/s4u-actor-create.cpp You create actors either: @@ -74,11 +74,11 @@ Starting and Stopping Actors .. tabs:: - .. example-tab:: examples/s4u/actor-exiting/s4u-actor-exiting.cpp + .. example-tab:: examples/cpp/actor-exiting/s4u-actor-exiting.cpp This example shows how to attach a callback to: - - the end of a specific actor: :cpp:func:`simgrid::s4u::this_actor::on_exit()` + - the end of a specific actor: :cpp:func:`simgrid::s4u::Actor::on_exit()` - the end of any actor: :cpp:member:`simgrid::s4u::Actor::on_termination()` - the destruction of any actor: :cpp:member:`simgrid::s4u::Actor::on_destruction()` @@ -92,10 +92,10 @@ Starting and Stopping Actors .. tabs:: - .. example-tab:: examples/s4u/actor-kill/s4u-actor-kill.cpp + .. example-tab:: examples/cpp/actor-kill/s4u-actor-kill.cpp See also :cpp:func:`void simgrid::s4u::Actor::kill(void)`, :cpp:func:`void simgrid::s4u::Actor::kill_all()`, - :cpp:func:`simgrid::s4u::this_actor::exit`, :cpp:func:`simgrid::s4u::this_actor::on_exit`. + :cpp:func:`simgrid::s4u::this_actor::exit`, :cpp:func:`simgrid::s4u::Actor::on_exit`. .. example-tab:: examples/python/actor-kill/actor-kill.py @@ -111,11 +111,11 @@ Starting and Stopping Actors .. tabs:: - .. example-tab:: examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp + .. example-tab:: examples/cpp/actor-lifetime/s4u-actor-lifetime.cpp This file is not really interesting: the important matter is in the XML file. - .. example-tab:: examples/s4u/actor-lifetime/s4u-actor-lifetime_d.xml + .. example-tab:: examples/cpp/actor-lifetime/s4u-actor-lifetime_d.xml This demonstrates the ``start_time`` and ``kill_time`` attribute of the :ref:`pf_tag_actor` tag. @@ -133,7 +133,7 @@ Starting and Stopping Actors .. tabs:: - .. example-tab:: examples/s4u/actor-daemon/s4u-actor-daemon.cpp + .. example-tab:: examples/cpp/actor-daemon/s4u-actor-daemon.cpp See also :cpp:func:`simgrid::s4u::Actor::daemonize()` and :cpp:func:`simgrid::s4u::Actor::is_daemon()`. @@ -152,7 +152,7 @@ Starting and Stopping Actors .. tabs:: - .. example-tab:: examples/s4u/actor-stacksize/s4u-actor-stacksize.cpp + .. example-tab:: examples/cpp/actor-stacksize/s4u-actor-stacksize.cpp .. example-tab:: examples/c/actor-stacksize/actor-stacksize.c @@ -168,7 +168,7 @@ synchronization objects `. .. tabs:: - .. example-tab:: examples/s4u/actor-suspend/s4u-actor-suspend.cpp + .. example-tab:: examples/cpp/actor-suspend/s4u-actor-suspend.cpp See also :cpp:func:`simgrid::s4u::this_actor::suspend()`, :cpp:func:`simgrid::s4u::Actor::suspend()`, :cpp:func:`simgrid::s4u::Actor::resume()`, and @@ -190,7 +190,7 @@ synchronization objects `. .. tabs:: - .. example-tab:: examples/s4u/actor-migrate/s4u-actor-migrate.cpp + .. example-tab:: examples/cpp/actor-migrate/s4u-actor-migrate.cpp See also :cpp:func:`simgrid::s4u::this_actor::set_host()` and :cpp:func:`simgrid::s4u::Actor::set_host()`. @@ -207,7 +207,7 @@ synchronization objects `. .. tabs:: - .. example-tab:: examples/s4u/actor-join/s4u-actor-join.cpp + .. example-tab:: examples/cpp/actor-join/s4u-actor-join.cpp See also :cpp:func:`simgrid::s4u::Actor::join()`. @@ -226,7 +226,7 @@ synchronization objects `. .. tabs:: - .. example-tab:: examples/s4u/actor-yield/s4u-actor-yield.cpp + .. example-tab:: examples/cpp/actor-yield/s4u-actor-yield.cpp See also :cpp:func:`simgrid::s4u::this_actor::yield()`. @@ -263,7 +263,7 @@ also the tesh files in the example directories for details. .. tabs:: - .. example-tab:: examples/s4u/replay-comm/s4u-replay-comm.cpp + .. example-tab:: examples/cpp/replay-comm/s4u-replay-comm.cpp - **I/O replay:** Presents a set of event handlers reproducing classical I/O @@ -271,7 +271,7 @@ also the tesh files in the example directories for details. .. tabs:: - .. example-tab:: examples/s4u/replay-io/s4u-replay-io.cpp + .. example-tab:: examples/cpp/replay-io/s4u-replay-io.cpp ========================== Activities: what Actors do @@ -282,6 +282,18 @@ Activities: what Actors do Communications on the Network ----------------------------- + - **Basic communications:** + This simple example just sends one message back and forth. + The tesh file laying in the directory show how to start the simulator binary, highlighting how to pass options to + the simulators (as detailed in Section :ref:`options`). + + .. tabs:: + + .. example-tab:: examples/cpp/comm-pingpong/s4u-comm-pingpong.cpp + + .. example-tab:: examples/c/comm-pingpong/comm-pingpong.c + + - **Basic asynchronous communications:** Illustrates how to have non-blocking communications, that are communications running in the background leaving the process free @@ -289,7 +301,7 @@ Communications on the Network .. tabs:: - .. example-tab:: examples/s4u/comm-wait/s4u-comm-wait.cpp + .. example-tab:: examples/cpp/comm-wait/s4u-comm-wait.cpp See also :cpp:func:`simgrid::s4u::Mailbox::put_async()` and :cpp:func:`simgrid::s4u::Comm::wait()`. @@ -301,6 +313,15 @@ Communications on the Network See also :cpp:func:`sg_mailbox_put_async()` and :cpp:func:`sg_comm__wait()`. + - **Waiting communications with timeouts:** + This example is very similar to the previous one, simply adding how to declare timeouts when waiting on asynchronous communication. + + .. tabs:: + + .. example-tab:: examples/cpp/comm-waituntil/s4u-comm-waituntil.cpp + + See also :cpp:func:`simgrid::s4u::Mailbox::wait_until()` and :cpp:func:`simgrid::s4u::Comm::wait_for()`. + - **Suspending communications:** The ``suspend()`` and ``resume()`` functions allow to block the progression of a given communication for a while and then unblock it. @@ -309,7 +330,7 @@ Communications on the Network .. tabs:: - .. example-tab:: examples/s4u/comm-suspend/s4u-comm-suspend.cpp + .. example-tab:: examples/cpp/comm-suspend/s4u-comm-suspend.cpp See also :cpp:func:`simgrid::s4u::Activity::suspend()` :cpp:func:`simgrid::s4u::Activity::resume()` and @@ -322,7 +343,7 @@ Communications on the Network .. tabs:: - .. example-tab:: examples/s4u/comm-waitall/s4u-comm-waitall.cpp + .. example-tab:: examples/cpp/comm-waitall/s4u-comm-waitall.cpp See also :cpp:func:`simgrid::s4u::Comm::wait_all()`. @@ -341,7 +362,7 @@ Communications on the Network .. tabs:: - .. example-tab:: examples/s4u/comm-waitany/s4u-comm-waitany.cpp + .. example-tab:: examples/cpp/comm-waitany/s4u-comm-waitany.cpp See also :cpp:func:`simgrid::s4u::Comm::wait_any()`. @@ -367,7 +388,7 @@ Executions on the CPU .. tabs:: - .. example-tab:: examples/s4u/exec-basic/s4u-exec-basic.cpp + .. example-tab:: examples/cpp/exec-basic/s4u-exec-basic.cpp See also :cpp:func:`void simgrid::s4u::this_actor::execute(double)` and :cpp:func:`void simgrid::s4u::this_actor::execute(double, double)`. @@ -387,7 +408,7 @@ Executions on the CPU .. tabs:: - .. example-tab:: examples/s4u/exec-async/s4u-exec-async.cpp + .. example-tab:: examples/cpp/exec-async/s4u-exec-async.cpp See also :cpp:func:`simgrid::s4u::this_actor::exec_init()`, :cpp:func:`simgrid::s4u::Activity::start()`, @@ -423,7 +444,7 @@ Executions on the CPU .. tabs:: - .. example-tab:: examples/s4u/exec-remote/s4u-exec-remote.cpp + .. example-tab:: examples/cpp/exec-remote/s4u-exec-remote.cpp See also :cpp:func:`simgrid::s4u::Exec::set_host()`. @@ -450,7 +471,7 @@ Executions on the CPU .. tabs:: - .. example-tab:: examples/s4u/exec-ptask/s4u-exec-ptask.cpp + .. example-tab:: examples/cpp/exec-ptask/s4u-exec-ptask.cpp See also :cpp:func:`simgrid::s4u::this_actor::parallel_execute()`. @@ -460,7 +481,7 @@ Executions on the CPU .. tabs:: - .. example-tab:: examples/s4u/exec-dvfs/s4u-exec-dvfs.cpp + .. example-tab:: examples/cpp/exec-dvfs/s4u-exec-dvfs.cpp See also :cpp:func:`simgrid::s4u::Host::get_pstate_speed` and :cpp:func:`simgrid::s4u::Host::set_pstate`. @@ -489,7 +510,7 @@ write actions on the disk resources. .. tabs:: - .. example-tab:: examples/s4u/io-disk-raw/s4u-io-disk-raw.cpp + .. example-tab:: examples/cpp/io-disk-raw/s4u-io-disk-raw.cpp .. example-tab:: examples/c/io-disk-raw/io-disk-raw.c @@ -508,7 +529,7 @@ result in short reads and short write, as in reality. .. tabs:: - .. example-tab:: examples/s4u/io-file-system/s4u-io-file-system.cpp + .. example-tab:: examples/cpp/io-file-system/s4u-io-file-system.cpp - **Remote I/O:** I/O operations on files can also be done in a remote fashion, @@ -516,7 +537,7 @@ result in short reads and short write, as in reality. .. tabs:: - .. example-tab:: examples/s4u/io-file-remote/s4u-io-file-remote.cpp + .. example-tab:: examples/cpp/io-file-remote/s4u-io-file-remote.cpp .. example-tab:: examples/c/io-file-remote/io-file-remote.c @@ -530,28 +551,37 @@ Classical synchronization objects .. tabs:: - .. example-tab:: examples/s4u/synchro-barrier/s4u-synchro-barrier.cpp + .. example-tab:: examples/cpp/synchro-barrier/s4u-synchro-barrier.cpp - - **Condition variable:** + - **Condition variable: basic usage** Shows how to use :cpp:type:`simgrid::s4u::ConditionVariable` synchronization objects. .. tabs:: - .. example-tab:: examples/s4u/synchro-condition-variable/s4u-synchro-condition-variable.cpp + .. example-tab:: examples/cpp/synchro-condition-variable/s4u-synchro-condition-variable.cpp + + - **Condition variable: timeouts** + Shows how to specify timeouts when blocking on condition variables. + + .. tabs:: + + .. example-tab:: examples/cpp/synchro-condition-variable-waituntil/s4u-synchro-condition-variable-waituntil.cpp - **Mutex:** Shows how to use :cpp:type:`simgrid::s4u::Mutex` synchronization objects. .. tabs:: - .. example-tab:: examples/s4u/synchro-mutex/s4u-synchro-mutex.cpp + .. example-tab:: examples/cpp/synchro-mutex/s4u-synchro-mutex.cpp - **Semaphore:** Shows how to use :cpp:type:`simgrid::s4u::Semaphore` synchronization objects. .. tabs:: - .. example-tab:: examples/s4u/synchro-semaphore/s4u-synchro-semaphore.cpp + .. example-tab:: examples/cpp/synchro-semaphore/s4u-synchro-semaphore.cpp + + .. example-tab:: examples/c/synchro-semaphore/synchro-semaphore.c ============================= Interacting with the Platform @@ -566,7 +596,7 @@ Interacting with the Platform .. tabs:: - .. example-tab:: examples/s4u/platform-properties/s4u-platform-properties.cpp + .. example-tab:: examples/cpp/platform-properties/s4u-platform-properties.cpp - :cpp:func:`simgrid::s4u::Actor::get_property()` and :cpp:func:`simgrid::s4u::Actor::set_property()` - :cpp:func:`simgrid::s4u::Host::get_property()` and :cpp:func:`simgrid::s4u::Host::set_property()` @@ -584,7 +614,7 @@ Interacting with the Platform **Deployment file:** - .. showfile:: examples/s4u/platform-properties/s4u-platform-properties_d.xml + .. showfile:: examples/cpp/platform-properties/s4u-platform-properties_d.xml :language: xml |br| @@ -598,14 +628,14 @@ Interacting with the Platform .. tabs:: - .. example-tab:: examples/s4u/routing-get-clusters/s4u-routing-get-clusters.cpp + .. example-tab:: examples/cpp/routing-get-clusters/s4u-routing-get-clusters.cpp - **Retrieving the list of hosts matching a given criteria:** Shows how to filter the actors that match a given criteria. .. tabs:: - .. example-tab:: examples/s4u/engine-filtering/s4u-engine-filtering.cpp + .. example-tab:: examples/cpp/engine-filtering/s4u-engine-filtering.cpp - **Specifying state profiles:** shows how to specify when the resources must be turned off and on again, and how to react to such @@ -613,7 +643,7 @@ Interacting with the Platform .. tabs:: - .. example-tab:: examples/s4u/platform-failures/s4u-platform-failures.cpp + .. example-tab:: examples/cpp/platform-failures/s4u-platform-failures.cpp .. example-tab:: examples/c/platform-failures/platform-failures.c @@ -633,7 +663,7 @@ Interacting with the Platform .. tabs:: - .. example-tab:: examples/s4u/platform-profile/s4u-platform-profile.cpp + .. example-tab:: examples/cpp/platform-profile/s4u-platform-profile.cpp .. group-tab:: XML @@ -674,7 +704,7 @@ Energy Simulation .. tabs:: - .. example-tab:: examples/s4u/energy-exec/s4u-energy-exec.cpp + .. example-tab:: examples/cpp/energy-exec/s4u-energy-exec.cpp .. example-tab:: examples/c/energy-exec/energy-exec.c @@ -684,7 +714,7 @@ Energy Simulation .. tabs:: - .. example-tab:: examples/s4u/energy-link/s4u-energy-link.cpp + .. example-tab:: examples/cpp/energy-link/s4u-energy-link.cpp - **Consumption due to the wireless network:** This example shows how to retrieve and display the energy consumed @@ -692,7 +722,7 @@ Energy Simulation .. tabs:: - .. example-tab:: examples/s4u/energy-wifi/s4u-energy-wifi.cpp + .. example-tab:: examples/cpp/energy-wifi/s4u-energy-wifi.cpp - **Modeling the shutdown and boot of hosts:** Simple example of model of model for the energy consumption during @@ -700,9 +730,9 @@ Energy Simulation .. tabs:: - .. example-tab:: examples/s4u/energy-boot/platform_boot.xml + .. example-tab:: examples/cpp/energy-boot/platform_boot.xml - .. example-tab:: examples/s4u/energy-boot/s4u-energy-boot.cpp + .. example-tab:: examples/cpp/energy-boot/s4u-energy-boot.cpp ======================= Tracing and Visualizing @@ -722,7 +752,7 @@ options to see the task executions: .. tabs:: - .. example-tab:: examples/s4u/trace-platform/s4u-trace-platform.cpp + .. example-tab:: examples/cpp/trace-platform/s4u-trace-platform.cpp - **Setting Categories** This example declares several tracing categories to that are used to @@ -733,7 +763,7 @@ options to see the task executions: .. tabs:: - .. example-tab:: examples/s4u/trace-categories/s4u-trace-categories.cpp + .. example-tab:: examples/cpp/trace-categories/s4u-trace-categories.cpp - **Master Workers tracing** This is an augmented version of our basic master/worker example using @@ -743,7 +773,7 @@ options to see the task executions: .. tabs:: - .. example-tab:: examples/s4u/trace-masterworkers/s4u-trace-masterworkers.cpp + .. example-tab:: examples/cpp/trace-masterworkers/s4u-trace-masterworkers.cpp - **Process migration tracing** This version is enhanced so that the process migrations can be displayed @@ -752,7 +782,7 @@ options to see the task executions: .. tabs:: - .. example-tab:: examples/s4u/trace-process-migration/s4u-trace-process-migration.cpp + .. example-tab:: examples/cpp/trace-process-migration/s4u-trace-process-migration.cpp .. TODO: These tracing examples should be integrated in the examples to not @@ -770,7 +800,7 @@ the following options: ``--cfg=tracing:yes --cfg=tracing/platform:yes`` .. tabs:: - .. example-tab:: examples/s4u/trace-host-user-variables/s4u-trace-host-user-variables.cpp + .. example-tab:: examples/cpp/trace-host-user-variables/s4u-trace-host-user-variables.cpp - **Attaching variables to Links** The tricky part is that you have to know the name of the link you want to @@ -778,7 +808,7 @@ the following options: ``--cfg=tracing:yes --cfg=tracing/platform:yes`` .. tabs:: - .. example-tab:: examples/s4u/trace-link-user-variables/s4u-trace-link-user-variables.cpp + .. example-tab:: examples/cpp/trace-link-user-variables/s4u-trace-link-user-variables.cpp - **Attaching variables to network Routes** It is often easier to update a given variable for all links of a given @@ -787,7 +817,7 @@ the following options: ``--cfg=tracing:yes --cfg=tracing/platform:yes`` .. tabs:: - .. example-tab:: examples/s4u/trace-route-user-variables/s4u-trace-route-user-variables.cpp + .. example-tab:: examples/cpp/trace-route-user-variables/s4u-trace-route-user-variables.cpp ======================== Larger SimGrid Examplars @@ -796,24 +826,13 @@ Larger SimGrid Examplars This section contains application examples that are somewhat larger than the previous examples. - - **Ping Pong:** - This simple example just sends one message back and forth. - The tesh file laying in the directory show how to start the simulator binary, highlighting how to pass options to - the simulators (as detailed in Section :ref:`options`). - - .. tabs:: - - .. example-tab:: examples/s4u/app-pingpong/s4u-app-pingpong.cpp - - .. example-tab:: examples/c/app-pingpong/app-pingpong.c - - **Token ring:** Shows how to implement a classical communication pattern, where a token is exchanged along a ring to reach every participant. .. tabs:: - .. example-tab:: examples/s4u/app-token-ring/s4u-app-token-ring.cpp + .. example-tab:: examples/cpp/app-token-ring/s4u-app-token-ring.cpp .. example-tab:: examples/c/app-token-ring/app-token-ring.c @@ -831,10 +850,10 @@ than the previous examples. more powerful for the users wanting to build their own projects upon the example). - .. showfile:: examples/s4u/app-masterworkers/s4u-app-masterworkers-class.cpp + .. showfile:: examples/cpp/app-masterworkers/s4u-app-masterworkers-class.cpp :language: cpp - .. showfile:: examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp + .. showfile:: examples/cpp/app-masterworkers/s4u-app-masterworkers-fun.cpp :language: cpp .. group-tab:: C @@ -852,13 +871,13 @@ Data diffusion .. group-tab:: C++ - .. showfile:: examples/s4u/app-bittorrent/s4u-bittorrent.cpp + .. showfile:: examples/cpp/app-bittorrent/s4u-bittorrent.cpp :language: cpp - .. showfile:: examples/s4u/app-bittorrent/s4u-peer.cpp + .. showfile:: examples/cpp/app-bittorrent/s4u-peer.cpp :language: cpp - .. showfile:: examples/s4u/app-bittorrent/s4u-tracker.cpp + .. showfile:: examples/cpp/app-bittorrent/s4u-tracker.cpp :language: cpp .. group-tab:: C @@ -877,7 +896,7 @@ Data diffusion .. tabs:: - .. example-tab:: examples/s4u/app-chainsend/s4u-app-chainsend.cpp + .. example-tab:: examples/cpp/app-chainsend/s4u-app-chainsend.cpp .. group-tab:: C @@ -900,10 +919,10 @@ Distributed Hash Tables (DHT) .. group-tab:: C++ - .. showfile:: examples/s4u/dht-chord/s4u-dht-chord.cpp + .. showfile:: examples/cpp/dht-chord/s4u-dht-chord.cpp :language: cpp - .. showfile:: examples/s4u/dht-chord/s4u-dht-chord-node.cpp + .. showfile:: examples/cpp/dht-chord/s4u-dht-chord-node.cpp :language: cpp - **Kademlia** @@ -913,16 +932,16 @@ Distributed Hash Tables (DHT) .. group-tab:: C++ - .. showfile:: examples/s4u/dht-kademlia/s4u-dht-kademlia.cpp + .. showfile:: examples/cpp/dht-kademlia/s4u-dht-kademlia.cpp :language: cpp - .. showfile:: examples/s4u/dht-kademlia/routing_table.cpp + .. showfile:: examples/cpp/dht-kademlia/routing_table.cpp :language: cpp - .. showfile:: examples/s4u/dht-kademlia/answer.cpp + .. showfile:: examples/cpp/dht-kademlia/answer.cpp :language: cpp - .. showfile:: examples/s4u/dht-kademlia/node.cpp + .. showfile:: examples/cpp/dht-kademlia/node.cpp :language: cpp .. group-tab:: C @@ -953,7 +972,7 @@ Simulating Clouds .. tabs:: - .. example-tab:: examples/s4u/cloud-simple/s4u-cloud-simple.cpp + .. example-tab:: examples/cpp/cloud-simple/s4u-cloud-simple.cpp .. example-tab:: examples/c/cloud-simple/cloud-simple.c @@ -962,7 +981,7 @@ Simulating Clouds .. tabs:: - .. example-tab:: examples/s4u/cloud-migration/s4u-cloud-migration.cpp + .. example-tab:: examples/cpp/cloud-migration/s4u-cloud-migration.cpp .. example-tab:: examples/c/cloud-migration/cloud-migration.c @@ -980,7 +999,7 @@ Model-Related Examples .. tabs:: - .. example-tab:: examples/s4u/network-ns3/s4u-network-ns3.cpp + .. example-tab:: examples/cpp/network-ns3/s4u-network-ns3.cpp .. group-tab:: XML @@ -1009,7 +1028,7 @@ Model-Related Examples .. tabs:: - .. example-tab:: examples/s4u/network-wifi/s4u-network-wifi.cpp + .. example-tab:: examples/cpp/network-wifi/s4u-network-wifi.cpp .. group-tab:: XML @@ -1036,7 +1055,7 @@ should be much easier than modifying the SimGrid kernel. .. tabs:: - .. example-tab:: examples/s4u/plugin-host-load/s4u-plugin-host-load.cpp + .. example-tab:: examples/cpp/plugin-host-load/s4u-plugin-host-load.cpp .. example-tab:: examples/c/plugin-host-load/plugin-host-load.c @@ -1044,7 +1063,7 @@ should be much easier than modifying the SimGrid kernel. .. tabs:: - .. example-tab:: examples/s4u/plugin-link-load/s4u-plugin-link-load.cpp + .. example-tab:: examples/cpp/plugin-link-load/s4u-plugin-link-load.cpp ======================= Model-Checking Examples @@ -1064,7 +1083,7 @@ SimGrid is slower and maybe less robust when MC is enabled. .. tabs:: - .. example-tab:: examples/s4u/mc-failing-assert/s4u-mc-failing-assert.cpp + .. example-tab:: examples/cpp/mc-failing-assert/s4u-mc-failing-assert.cpp .. |br| raw:: html