Re: [Gnash-commit] gnash ChangeLog libbase/LoadThread.h

[strk]

On Fri, Mar 09, 2007 at 11:15:58PM +0000, Tomas Groth wrote:

> +/// \brief
> +/// The LoadThread class can be used to download from a file
> +/// or stream using a thread, without having to block.

Add an empy comment line here to separate the "brief" description from
the "long" description.

> +/// When the object is created it starts a thread which downloads
> +/// from the tu_file given as an argument to the constructor, and
> +/// keeps downloading until the download is complete. It is possible
> +/// for the object owner to query for data, position, loaded data,
> +/// total data while downloading, without blocking.

It seems *important* that the caller won't use the tu_file itself or
I guess bad thing would happen. The best way to ensure this is to pass
the tu_file as a std::auto_ptr, which encodes ownership transfer in
a standard way.

> +Though if there has 
> +/// not been downloaded enough data to accomendate a request (seek/read)
> +/// it will block until the data is present (curl_adaptor behavoir).

noseek_fd_adapter behaviour too, if worth mentioning.
Btw, should we provide non-blocking try_seek/try_read methods ?
[ inlined, using getBytesLoaded()-tell() ]

> +///
> +/// When using the LoadThread, all access to the tu_file should be
> +/// done through LoadThread, or it will likely break.

Right, seee above (auto_ptr)

> +///
> +/// @todo When we read from a real movie stream (rtmp) we might
> +/// want to use a cirkular-buffer.

Mmm... I'm not convinced about this, what if user requests seek(0) ?

>  class LoadThread
>  {
>  
>  public:
> +     /// Creating the object starts the threaded loading 
> +     /// of the stream/file passed as an argument.
>       LoadThread(tu_file* stream);

A *single* line will be taken as "brief" desciption, multiple
lines will need a \brief specification to be taken as "brief"

>       ~LoadThread();

Canceal the thread ? joins it ?

>  
>       /// Put read pointer at given position
> +     /// Will block if there is not enough data buffered,
> +     /// and wait until enough data is present.
>       bool seek(size_t pos);

@see getBytesLoaded

>       /// Read 'bytes' bytes into the given buffer.
> -     /// Return number of actually read bytes
> +     /// Return number of actually read bytes.
> +     /// Will block if there is not enough data buffered,
> +     /// and wait until enough data is present.
>       size_t read(void *dst, size_t bytes);

@see getBytesLoaded

>  
>       /// Return true if EOF has been reached

(by read or seek ops)


Thank you, it's being very useful.

--strk;