the number of events requested is passed or the end position is reached. When
this function ends, the end position can be extracted from the context, the end
event is set as described below and the number of events read is returned.
the number of events requested is passed or the end position is reached. When
this function ends, the end position can be extracted from the context, the end
event is set as described below and the number of events read is returned.