---

strmod::strmod::StreamModule::Plug Class Reference

A point of connection between one StreamModule and another. More...

#include <StrMod/StreamModule.h>

Inheritance diagram for strmod::strmod::StreamModule::Plug:

[legend]List of all members.

Public Methods
	Plug (StreamModule &parent)
	A Plug has to have a parent.
virtual	~Plug ()
	Does some tricky things to avoid having the disconnect strategy called.
virtual int	AreYouA (const lcore::ClassIdent &cid) const
bool	isReadable () const
	Can this plug be read from?
bool	isWriteable () const
	Can this plug be written to?
bool	plugInto (Plug &other)
	Plug this plug into another. Can fail if already plugged in.
void	unPlug ()
	Unplug this plug from any plugs it may be connected to.
Plug *	pluggedInto () const
	Which plug (if any) is this plug plugged into? Returns NULL if not plugged in.
StreamModule &	getParent () const
	Which module owns this plug?
virtual int	side () const=0
	Which 'side' is this plug on?
Static Public Attributes
const STR_ClassIdent	identifier
	A unique identifier for this class.
Protected Methods
virtual const lcore::ClassIdent *	i_GetIdent () const
void	setReadable (bool val)
	Set whether this plug is readable or not.
void	setWriteable (bool val)
	Set whether this plug is writeable or not.
void	setIsReading (bool val)
	These are so derived classes have access to this flag.
void	setIsWriting (bool val)
	These are so derived classes have access to this flag.
void	notifyOtherReadable () const
	Tell a connected plug that this plug's readable state has changed.
void	notifyOtherWriteable () const
	Tell a connected plug that this plug's readable state has changed.
virtual bool	needsNotifyReadable () const
	If this plug needs to be notified of the other's readable state.
virtual bool	needsNotifyWriteable () const
	If this plug needs to be notified of the other's writeable state.
virtual void	otherIsReadable ()
	The 'other plug's readable state changed' notification function.
virtual void	otherIsWriteable ()
	The 'other plug's writeable state changed' notification function.
void	writeOther (const StrChunkPtr &ptr) const
	This is so derived classes can call write on the connected plug.
const StrChunkPtr	readOther () const
	This is so derived classes can call read on the connected plug.
Read and Write
Actually read or write to a StreamModule::Plug. These functions have undefined behavior when the appropriate isReadable or isWriteable function returns false. Also, to avoid re-entrancy problems, the flag_.isreading_ or flag_.iswriting_ flag should be set before actually doing the read or write. This prevents the read or write from causing the function to be called again. This is of particular importance for modules like EchoModule. If you have two EchoModule objects with a buffering module of some sort between then, an infinitely recurisve loop could easily be formed if a read or write function were called without the appropriate re-entrancy control flag being set. As it is, you will get an infinite loop, but it will not be recursive, so the program will not crash. (You might have wanted the infinite loop for some reason.)
virtual const StrChunkPtr	i_Read ()=0
	Read this this plug. Behavior is undefined if this plug not readable.
virtual void	i_Write (const StrChunkPtr &ptr)=0
	Write to this plug. Behavior is undefined if this plug not writeable.
Push and pulll loops
The loops that get everything done. Because of these loops, and the infrastructure that exists in the base StreamModule and StreamModule::Plug class that calls them, you should never have to call i_Read() or i_Write(). These member functions are part of that infrastructure. They handle setting the iswriting_ and isreading_ flags properly. They also loop until no more data can be moved in the direction they're moving it because one Plug became unwriteable, or one plug became unreadable. In short, don't bypass them unless you really know what you're doing.
void	pushLoop ()
	Read as much as possible from this plug and write to the connected plug.
void	pullLoop ()
	Read as much as possible from the connected plug and write to this plug.
Static Protected Methods
void	setIsReading (Plug &othr, bool v)
	These are so derived classes have access to this flag on other plugs.
void	setIsWriting (Plug &othr, bool v)
	These are so derived classes have access to this flag on other plugs.
const Flags &	getFlagsFrom (const Plug &p)
	This is so derived classes can get read access to the flags of any plug.
Friends
class	StreamModule

---

Detailed Description

A point of connection between one StreamModule and another.

Definition at line 195 of file StreamModule.h.

---

Member Function Documentation

virtual const StrChunkPtr strmod::strmod::StreamModule::Plug::i_Read (    )  [protected, pure virtual]

Read this this plug. Behavior is undefined if this plug not readable. When writing your own read function that calls this one, you are responsible for making sure the the plug is readable before calling this function. These functions do not set the isreading or iswriting flags. You'll need to write wrapper functions that do this. The pushLoop and pullLoop functions already set the isreading and iswriting flags. Implemented in strmod::strmod::SockListenModule::SLPlug.

virtual void strmod::strmod::StreamModule::Plug::i_Write (  const StrChunkPtr &    ptr )  [protected, pure virtual]

Write to this plug. Behavior is undefined if this plug not writeable. When writing your own write function that calls this one, you are responsible for making sure the the plug is writeable before calling this function. These functions do not set the isreading or iswriting flags. You'll need to write wrapper functions that do this. The pushLoop and pullLoop functions already set the isreading and iswriting flags. Implemented in strmod::strmod::SockListenModule::SLPlug.

virtual bool strmod::strmod::StreamModule::Plug::needsNotifyReadable (    )  const [inline, protected, virtual]

If this plug needs to be notified of the other's readable state. The only plugs that should really need this are ones for modules where the readable or writeable state of certain plugs depends on the readable state of the plug that this plug is plugged into. Definition at line 293 of file StreamModule.h.

virtual bool strmod::strmod::StreamModule::Plug::needsNotifyWriteable (    )  const [inline, protected, virtual]

If this plug needs to be notified of the other's writeable state. The only plugs that should really need this are ones for modules where the readable or writeable state of certain plugs depends on the writeable state of the plug that this plug is plugged into. Definition at line 301 of file StreamModule.h.

void strmod::strmod::StreamModule::Plug::notifyOtherReadable (    )  const [inline, protected]

Tell a connected plug that this plug's readable state has changed. This checks the flags first and doesn't notify if the other plug doesn't request notification. Definition at line 527 of file StreamModule.h.

void strmod::strmod::StreamModule::Plug::notifyOtherWriteable (    )  const [inline, protected]

Tell a connected plug that this plug's readable state has changed. This checks the flags first and doesn't notify if the other plug doesn't request notification. Definition at line 536 of file StreamModule.h.

virtual void strmod::strmod::StreamModule::Plug::otherIsReadable (    )  [inline, protected, virtual]

The 'other plug's readable state changed' notification function. Called when plug this plug is plugged into changes whether or not it is readable. Definition at line 309 of file StreamModule.h.

virtual void strmod::strmod::StreamModule::Plug::otherIsWriteable (    )  [inline, protected, virtual]

The 'other plug's writeable state changed' notification function. Called when plug this plug is plugged into changes whether or not it is writeable. Definition at line 316 of file StreamModule.h.

bool strmod::strmod::StreamModule::Plug::plugInto (  Plug &    other )

Plug this plug into another. Can fail if already plugged in. Parameters: other  A reference to the plug to plug into. (A pointer to it is stored). A pointer to other will be stored by the plug until it's unplugged or destroyed. other is a reference because it's not allowed to be NULL. Definition at line 43 of file StreamModule.cxx.

void strmod::strmod::StreamModule::Plug::pullLoop (    )  [protected]

Read as much as possible from the connected plug and write to this plug. This keeps the isreading and iswriting flags set until the loop exits. This loop can exit for a number of reasons, including disconnection, one side 'drying up' and having nothing to read, or one side 'filling up' and not being able to be written to. Definition at line 143 of file StreamModule.cxx.

void strmod::strmod::StreamModule::Plug::pushLoop (    )  [protected]

Read as much as possible from this plug and write to the connected plug. This keeps the isreading and iswriting flags set until the loop exits. This loop can exit for a number of reasons, including disconnection, one side 'drying up' and having nothing to read, or one side 'filling up' and not being able to be written to. Definition at line 102 of file StreamModule.cxx.

void strmod::strmod::StreamModule::Plug::setReadable (  bool    val )  [inline, protected]

Set whether this plug is readable or not. Even if this is set, isReadable can return false because the plug is already being read from, and a plug can't be read by two things at once. Definition at line 489 of file StreamModule.h.

void strmod::strmod::StreamModule::Plug::setWriteable (  bool    val )  [inline, protected]

Set whether this plug is writeable or not. Even if this is set, isWriteable can return false because the plug is already being written to, and a plug can't be written to by two things at once. Definition at line 505 of file StreamModule.h.

---

The documentation for this class was generated from the following files:

• StreamModule.h
• StreamModule.cxx

---