Need an API to know when a symbol has been effectively written to the bitstream

[Yoric]

Whenever we call Codec::compress_symbol, this often does not output bits immediately to the bitstream. However, for compression, knowing when a symbol has effectively been written is often critical (e.g. to insert an inline dictionary, of for streaming purposes).

I'd like an API to know that.

[Yoric]

Maybe something along the lines of

struct Coder<W, M> where W: BitWrite, M: Model {
  // ...
}

impl Coder<W, M> where W: BitWrite, M: Model {
  fn new(write: W, model: M) -> Self;
  fn push_symbol(&mut self, symbol: usize) -> impl Future<Item = usize /* symbols written since start */, Error = Error>;
  fn flush(&mut self) -> Result<(W, M, usize /*bytes written*/), (W, M, E)>;
}

with the invariant that a symbol is never partially written.

[Yoric]

Actually, a simpler API might be

#[derive(Clone, Debug, Copy, PartialEq, Eq)]
pub struct PendingBytes(pub usize);

impl Codec {
  /// In case of success, return `Ok(pending)`, where `pending` is the number of symbols
  /// that are still pending.
  ///
  /// In other terms, if `PendingBytes.0 == 0`, `symbol` has been written to `output`.
  /// If `PendingBytes.0 == 1`, all the symbols except `symbol` have been written to `output`,
  /// etc.
  fn compress_symbol(&mut self, symbol: usize, output: &mut BitWrite) -> Result<PendingBytes>;
}