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 a feature that allows your code to be called back from many places:
  * during data transfers
  * when you are waiting for data

Heartbeats are periodical. If you set hearbeat frequency to twice per second and Synapse spends 2 seconds waiting for data, then heartbeat occurs four times, e.g. each half-second.
===== What is it useful for? =====

You can use heartbeat to handle your GUI, for example. In a simple application, making communication calls from the main thread may freeze GUI. You can avoid that by processing GUI events in your heartbeat code.

Also, each heartbeat tests for //StopFlag//, which allows your application to instantly respond to user's //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.