/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* The Original Code is mozilla.org code.
*
* The Initial Developer of the Original Code is
* Netscape Communications Corporation.
* Portions created by the Initial Developer are Copyright (C) 1999
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
*
* Alternatively, the contents of this file may be used under the terms of
* either of the GNU General Public License Version 2 or later (the "GPL"),
* or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
#ifndef _MORKSTREAM_
#define _MORKSTREAM_ 1
#ifndef _MORK_
#include "mork.h"
#endif
#ifndef _MORKNODE_
#include "morkNode.h"
#endif
#ifndef _MORKFILE_
#include "morkFile.h"
#endif
//3456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789
/*=============================================================================
* morkStream: buffered file i/o
*/
/*| morkStream exists to define an morkFile subclass that provides buffered
**| i/o for an underlying content file. Naturally this arrangement only makes
**| sense when the underlying content file is itself not efficiently buffered
**| (especially for character by character i/o).
**|
**|| morkStream is intended for either reading use or writing use, but not
**| both simultaneously or interleaved. Pick one when the stream is created
**| and don't change your mind. This restriction is intended to avoid obscure
**| and complex bugs that might arise from interleaved reads and writes -- so
**| just don't do it. A stream is either a sink or a source, but not both.
**|
**|| (When the underlying content file is intended to support both reading and
**| writing, a developer might use two instances of morkStream where one is for
**| reading and the other is for writing. In this case, a developer must take
**| care to keep the two streams in sync because each will maintain a separate
**| buffer representing a cache consistency problem for the other. A simple
**| approach is to invalidate the buffer of one when one uses the other, with
**| the assumption that closely mixed reading and writing is not expected, so
**| that little cost is associated with changing read/write streaming modes.)
**|
**|| Exactly one of mStream_ReadEnd or mStream_WriteEnd must be a null pointer,
**| and this will cause the right thing to occur when inlines use them, because
**| mStream_At < mStream_WriteEnd (for example) will always be false and the
**| else branch of the statement calls a function that raises an appropriate
**| error to complain about either reading a sink or writing a source.
**|
**|| morkStream is a direct clone of ab_Stream from Communicator 4.5's
**| address book code, which in turn was based on the stream class in the
**| public domain Mithril programming language.
|*/
#define morkStream_kPrintBufSize /*i*/ 512 /* buffer size used by printf() */
#define morkStream_kMinBufSize /*i*/ 512 /* buffer no fewer bytes */
#define morkStream_kMaxBufSize /*i*/ (32 * 1024) /* buffer no more bytes */
#define morkDerived_kStream /*i*/ 0x7A74 /* ascii 'zt' */
class morkStream /*d*/ : public morkFile { /* from Mithril's AgStream class */
// ````` ````` ````` ````` ````` ````` ````` `````
protected: // protected morkStream members
mork_u1* mStream_At; // pointer into mStream_Buf
mork_u1* mStream_ReadEnd; // null or one byte past last readable byte
mork_u1* mStream_WriteEnd; // null or mStream_Buf + mStream_BufSize
nsIMdbFile* mStream_ContentFile; // where content is read and written
mork_u1* mStream_Buf; // dynamically allocated memory to buffer io
mork_size mStream_BufSize; // requested buf size (fixed by min and max)
mork_pos mStream_BufPos; // logical position of byte at mStream_Buf
mork_bool mStream_Dirty; // does the buffer need to be flushed?
mork_bool mStream_HitEof; // has eof been reached? (only frozen streams)
// { ===== begin morkNode interface =====
public: // morkNode virtual methods
virtual void CloseMorkNode(morkEnv* ev) override; // CloseStream() only if open
virtual ~morkStream(); // assert that CloseStream() executed earlier
public: // morkStream construction & destruction
morkStream(morkEnv* ev, const morkUsage& inUsage, nsIMdbHeap* ioHeap,
nsIMdbFile* ioContentFile, mork_size inBufSize, mork_bool inFrozen);
void CloseStream(morkEnv* ev); // called by CloseMorkNode();
private: // copying is not allowed
morkStream(const morkStream& other);
morkStream& operator=(const morkStream& other);
public: // dynamic type identification
mork_bool IsStream() const
{ return IsNode() && mNode_Derived == morkDerived_kStream; }
// } ===== end morkNode methods =====
public: // typing
void NonStreamTypeError(morkEnv* ev);
// ````` ````` ````` ````` ````` ````` ````` `````
public: // virtual morkFile methods
NS_IMETHOD Steal(nsIMdbEnv* ev, nsIMdbFile* ioThief) override;
// Steal: tell this file to close any associated i/o stream in the file
// system, because the file ioThief intends to reopen the file in order
// to provide the MDB implementation with more exotic file access than is
// offered by the nsIMdbFile alone. Presumably the thief knows enough
// from Path() in order to know which file to reopen. If Steal() is
// successful, this file should probably delegate all future calls to
// the nsIMdbFile interface down to the thief files, so that even after
// the file has been stolen, it can still be read, written, or forcibly
// closed (by a call to CloseMdbObject()).
NS_IMETHOD BecomeTrunk(nsIMdbEnv* ev) override;
// If this file is a file version branch created by calling AcquireBud(),
// BecomeTrunk() causes this file's content to replace the original
// file's content, typically by assuming the original file's identity.
NS_IMETHOD AcquireBud(nsIMdbEnv* ev, nsIMdbHeap* ioHeap, nsIMdbFile** acqBud) override;
// AcquireBud() starts a new "branch" version of the file, empty of content,
// so that a new version of the file can be written. This new file
// can later be told to BecomeTrunk() the original file, so the branch
// created by budding the file will replace the original file. Some
// file subclasses might initially take the unsafe but expedient
// approach of simply truncating this file down to zero length, and
// then returning the same morkFile pointer as this, with an extra
// reference count increment. Note that the caller of AcquireBud() is
// expected to eventually call CutStrongRef() on the returned file
// in order to release the strong reference. High quality versions
// of morkFile subclasses will create entirely new files which later
// are renamed to become the old file, so that better transactional
// behavior is exhibited by the file, so crashes protect old files.
// Note that AcquireBud() is an illegal operation on readonly files.
virtual mork_pos Length(morkEnv* ev) const override; // eof
NS_IMETHOD Tell(nsIMdbEnv* ev, mork_pos *aOutPos ) const override;
NS_IMETHOD Read(nsIMdbEnv* ev, void* outBuf, mork_size inSize, mork_size *aOutCount) override;
NS_IMETHOD Seek(nsIMdbEnv* ev, mork_pos inPos, mork_pos *aOutPos) override;
NS_IMETHOD Write(nsIMdbEnv* ev, const void* inBuf, mork_size inSize, mork_size *aOutCount) override;
NS_IMETHOD Flush(nsIMdbEnv* ev) override;
// ````` ````` ````` ````` ````` ````` ````` `````
protected: // protected non-poly morkStream methods (for char io)
int fill_getc(morkEnv* ev);
void spill_putc(morkEnv* ev, int c);
void spill_buf(morkEnv* ev); // spill/flush from buffer to file
// ````` ````` ````` ````` ````` ````` ````` `````
public: // public non-poly morkStream methods
void NewBadCursorSlotsError(morkEnv* ev) const;
void NewBadCursorOrderError(morkEnv* ev) const;
void NewNullStreamBufferError(morkEnv* ev) const;
void NewCantReadSinkError(morkEnv* ev) const;
void NewCantWriteSourceError(morkEnv* ev) const;
void NewPosBeyondEofError(morkEnv* ev) const;
nsIMdbFile* GetStreamContentFile() const { return mStream_ContentFile; }
mork_size GetStreamBufferSize() const { return mStream_BufSize; }
mork_size PutIndent(morkEnv* ev, mork_count inDepth);
// PutIndent() puts a linebreak, and then
// "indents" by inDepth, and returns the line length after indentation.
mork_size PutByteThenIndent(morkEnv* ev, int inByte, mork_count inDepth);
// PutByteThenIndent() puts the byte, then a linebreak, and then
// "indents" by inDepth, and returns the line length after indentation.
mork_size PutStringThenIndent(morkEnv* ev,
const char* inString, mork_count inDepth);
// PutStringThenIndent() puts the string, then a linebreak, and then
// "indents" by inDepth, and returns the line length after indentation.
mork_size PutString(morkEnv* ev, const char* inString);
// PutString() returns the length of the string written.
mork_size PutStringThenNewline(morkEnv* ev, const char* inString);
// PutStringThenNewline() returns total number of bytes written.
mork_size PutByteThenNewline(morkEnv* ev, int inByte);
// PutByteThenNewline() returns total number of bytes written.
// ````` ````` stdio type methods ````` `````
void Ungetc(int c) /*i*/
{ if ( mStream_At > mStream_Buf && c > 0 ) *--mStream_At = (mork_u1) c; }
// Note Getc() returns EOF consistently after any fill_getc() error occurs.
int Getc(morkEnv* ev) /*i*/
{ return ( mStream_At < mStream_ReadEnd )? *mStream_At++ : fill_getc(ev); }
void Putc(morkEnv* ev, int c) /*i*/
{
mStream_Dirty = morkBool_kTrue;
if ( mStream_At < mStream_WriteEnd )
*mStream_At++ = (mork_u1) c;
else
spill_putc(ev, c);
}
mork_size PutLineBreak(morkEnv* ev);
public: // typesafe refcounting inlines calling inherited morkNode methods
static void SlotWeakStream(morkStream* me,
morkEnv* ev, morkStream** ioSlot)
{ morkNode::SlotWeakNode((morkNode*) me, ev, (morkNode**) ioSlot); }
static void SlotStrongStream(morkStream* me,
morkEnv* ev, morkStream** ioSlot)
{ morkNode::SlotStrongNode((morkNode*) me, ev, (morkNode**) ioSlot); }
};
//3456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789
#endif /* _MORKSTREAM_ */