Add function lsl_inlet_flush() to drop all outstanding samples from an inlet to avoid the pull_ overhead in realtime applications

Author: tstenner

include/lsl/inlet.h

@@ -273,6 +273,9 @@ extern LIBLSL_C_API unsigned long lsl_pull_chunk_buf(lsl_inlet in, char **data_b
 */
 extern LIBLSL_C_API uint32_t lsl_samples_available(lsl_inlet in);
 
+/// Drop all queued not-yet pulled samples, return the nr of dropped samples
+extern LIBLSL_C_API uint32_t lsl_inlet_flush(lsl_inlet in);
+
 /**
 * Query whether the clock was potentially reset since the last call to lsl_was_clock_reset().
 *

include/lsl_cpp.h

@@ -1575,6 +1575,9 @@ class stream_inlet {
 	 */
 	std::size_t samples_available() { return lsl_samples_available(obj); }
 
+	/// Drop all queued not-yet pulled samples, return the nr of dropped samples
+	uint32_t flush() noexcept { return lsl_inlet_flush(obj); }
+
 	/**
 	 * Query whether the clock was potentially reset since the last call to was_clock_reset().
 	 *

src/consumer_queue.cpp

@@ -46,4 +46,10 @@ sample_p consumer_queue::pop_sample(double timeout) {
 	return result;
 }
 
+uint32_t consumer_queue::flush() noexcept {
+	uint32_t n = 0;
+	while (buffer_.pop()) n++;
+	return n;
+}
+
 bool consumer_queue::empty() { return buffer_.empty(); }

src/consumer_queue.h

@@ -37,6 +37,12 @@ class consumer_queue : private lslboost::noncopyable {
 	 */
 	sample_p pop_sample(double timeout = FOREVER);
 
+	/// Number of available samples
+	std::size_t read_available() const { return buffer_.read_available(); }
+
+	/// Flush the queue, return the number of dropped samples
+	uint32_t flush() noexcept;
+
 	/// Check whether the buffer is empty.
 	bool empty();
 

src/data_receiver.h

@@ -70,6 +70,9 @@ class data_receiver : public cancellable_registry {
 	/// Check whether the underlying buffer is empty. This value may be inaccurate.
 	bool empty() { return sample_queue_.empty(); }
 
+	/// Flush the queue, return the number of dropped samples
+	uint32_t flush() noexcept { return sample_queue_.flush(); }
+
 private:
 	/// The data reader thread.
 	void data_thread();

src/lsl_inlet_c.cpp

@@ -357,6 +357,10 @@ LIBLSL_C_API uint32_t lsl_samples_available(lsl_inlet in) {
 	} catch (std::exception &) { return 0; }
 }
 
+LIBLSL_C_API uint32_t lsl_inlet_flush(lsl_inlet in) {
+	return in->flush();
+}
+
 LIBLSL_C_API uint32_t lsl_was_clock_reset(lsl_inlet in) {
 	try {
 		return (uint32_t)in->was_clock_reset();

src/stream_inlet_impl.h

@@ -304,6 +304,9 @@ class stream_inlet_impl {
 	 */
 	std::size_t samples_available() { return (std::size_t)(!data_receiver_.empty()); }
 
+	/// Flush the queue, return the number of dropped samples
+	uint32_t flush() { return !data_receiver_.flush(); }
+
 	/** Query whether the clock was potentially reset since the last call to was_clock_reset().
 	 *
 	 * This is only interesting for applications that combine multiple time_correction values to