/******************************************/
/* streamers.h 0.3.0 (1999-Dec-18-Sat)    */
/* Adam M. Costello <amc@cs.berkeley.edu> */
/******************************************/

/* Example objects that produce and consume bytes, and */
/* conform to the interface of bytestream.h 0.2.x.     */

/* This is ANSI C code. */


#ifndef STREAMERS_H
#define STREAMERS_H


#include "bytestream.h"
#include "integer.h"


struct streamer_parameters {
  unsigned long total_bytes;  /* number of bytes to send or expect */
  uint32 seed;                /* seed for the pseudo-random data   */
  double rate;                /* average bits/s to send or accept  */
  unsigned long burst_min;    /* smallest possible burst, in bytes */
  unsigned long burst_max;    /* largest possible burst, in bytes  */
};

/* The byte source randomly (and uniformly) chooses a burst size   */
/* b, waits enough time to generate the burst at the given rate,   */
/* instantaneously creates that much new data, sends it as fast as */
/* the recipient will accept it, then repeats the procedure.  But  */
/* it will not create more than total_bytes.  The data will be a   */
/* pseudo-random sequence determined by the specified seed.        */

/* The byte sink randomly (and uniformly) chooses a burst size b,     */
/* immediately becomes willing to accept that much additional data,   */
/* proceeds to process that much data at the given rate as it arrives */
/* (storing the data in an infinite buffer if it arrives faster than  */
/* it is processed), then repeats the procedure.  If data arrives     */
/* more slowly than it can be processed, the processing will pause    */
/* while there is no data available.  The sink will expect the data   */
/* to be a pseudo-random sequence determined by the specified seed,   */
/* and will complain if different data arrives, or if more than       */
/* total_bytes arrives.  So you want the total_bytes and seed to be   */
/* the same for both the source and sink, but not necessarily the     */
/* other parameters.  Note that setting the sink's burst_min greater  */
/* than total_bytes causes it to accept data as fast as it arrives.   */

/* burst_min must be at least 1 and no more than burst_max. */


void *byte_source_create(void);

    /* Returns a unique identifier for a new */
    /* byte source with default parameters.  */


void byte_source_config(void *source, struct streamer_parameters parameters);

    /* Configures the byte source with the given parameters.  A byte */
    /* source can be reconfigured while it is running, but the seed  */
    /* is looked at only once, when byte_source_talk_to() is called. */


void byte_source_talk_to(
  void *source,
  void *sink,
  bytestream_transfer_method *transfer );

    /* Tells the specified byte source to start sending data to the  */
    /* specified sink using the specified transfer method.  Must not */
    /* be called more than once per byte source.                     */


bytestream_go_ahead_method byte_source_go_ahead;

    /* The source's go-ahead method. */


unsigned long byte_source_sent(void *source);

    /* Returns the total number of bytes sent by the byte source. */


void byte_source_delete(void *byte_source);

    /* Deletes the byte source, which must not be referenced anymore. */


void *byte_sink_create(void);

    /* Returns a unique identifier for a new */
    /* byte sink with default parameters.    */


void byte_sink_config(void *sink, struct streamer_parameters parameters);

    /* Configures the byte sink with the given parameters.  A byte   */
    /* sink can be reconfigured while it is running, but the seed is */
    /* looked at only once, when byte_sink_listen_to() is called.    */


void byte_sink_listen_to(
  void *sink,
  void *source,
  bytestream_go_ahead_method *go_ahead );

    /* Tells the specified byte sink to start expecting to  */
    /* receive data from the specified sink, and to use     */
    /* the specified go-ahead method.  Must not be called   */
    /* more than once per byte sink.  Notice that the order */
    /* of the source and sink parameters is opposite for    */
    /* the byte_source_send_to and byte_sink_receive_from   */
    /* methods.  The convention is that the callee comes    */
    /* first.                                               */


bytestream_transfer_method byte_sink_transfer;

    /* The sink's transfer method. */


unsigned long byte_sink_received(void *sink);

    /* Returns the total number of bytes received by the byte sink. */


unsigned long byte_sink_wrong(void *sink);

    /* Returns the total number of incorrect */
    /* bytes received by the byte sink.      */


void byte_sink_delete(void *sink);

    /* Deletes the byte sink, which must not be referenced anymore. */


#endif /* STREAMERS_H */