public:howto:heartbeat [Ararat Synapse]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Heartbeats ======

Sometimes you need to call your code during data transfer. You can hook OnStatus event, but it's called by comunication events only.

For example, when sending data, onStatus is fired for each sent packet. But on slow connection that wouldn't happen too often. You can decrease sending chunk size, but it's not optimal for fast networks. When receiving data, it depends on received packets size. As you can see, this event is not ideal for calling your code periodicaly during data transfers.

===== What is heartbeat? =====

Heartbeat is feature what allows to call your code on many places:
  * during data transfers
  * when you are waiting for data

Heartbeats are periodical. If you set hearbeat to be called 2 times in second, then if Syapse waiting for received datas 2 secodns, then heartbeat is called four times, each half of second.

===== For what it is useful? =====

You can use Heartbeats for handle your GUI, for example. In some easy applications you not need to call communication in separate thread. You can made your application smooth responsible by processing of your GUI in your Heartbeat code.

Additonally, each heratbeat testing //StopFlag// too! It can made your application very fast responsible to user 'cancel' action.


===== How to use it? =====

Hook your code to //OnHeartbeat// event. Then you must set //HeartbeatRate// property. Default value 0 turing off this feature. Value is in milliseconds and define typical time for calling next heartbeat. But in some cases heartbeat can be called more often then this rate!

:!: Each heartbeat need some time for processing. Do not call heartbeats too often! Set HeartbeatRate carefully and use reasonable values.