API and stability improvements

git-svn-id: file:///srv/svn/repos/haiku/trunk/current@1318 a95241bf-73f2-0310-859d-f6bbb57e9c96

docs/develop/app/usecases/PortLinkUseCases.htm

@@ -34,11 +34,11 @@ The document has the following sections:</P>
 
 <LI><P><B>Creating a message:</B> Creating a message can be as simple as setting the message code (similar to BMessage's <i>what</i> member). Extra data is not required.</P></LI>
 
-<LI><P><B>Attaching Data:</B> Adding extra data is as simple as calling the member function Attach(), which makes a copy of the parameter passed to it.</P></LI>
+<LI><P><B>Attaching Data:</B> Adding extra data is as simple as calling the member function Attach(), which makes a copy of the parameter passed to it. B_ERROR is returned if the no more data can be attached before the message is sent or if the size is invalid. B_NO_MEMORY is returned when the attachments are larger than the target port's capacity.</P></LI>
 
-<LI><P><B>Sending a message:</B> Call Flush(). Whatever opcode has been set will be sent to the target. Optionally, a timeout (in microseconds) of type bigtime_t can be specified. This can be useful in preventing deadlocks if the target has crashed and its port fills up.</P></LI>
+<LI><P><B>Sending a message:</B> Call Flush(). Whatever opcode has been set will be sent to the target. Optionally, a timeout (in microseconds) of type bigtime_t can be specified. This can be useful in preventing deadlocks if the target has crashed and its port fills up. The function returns B_BAD_VALUE if the target port is invalid.</P></LI>
 
-<LI><P><B>Synchronous Messaging:</B> This one requires a little more care in order to prevent deadlocks. Attachments may be used as with Flush(), but FlushWithReply() will wait until the target replies unless a timeout value is specified in microseconds of type bigtime_t. A return code of B_ERROR indicates an internal data error and your message is intact. If a reply times out, it will return B_TIMED_OUT. Otherwise, it returns B_OK.
+<LI><P><B>Synchronous Messaging:</B> This one requires a little more care in order to prevent deadlocks. Attachments may be used as with Flush(), but FlushWithReply() will wait until the target replies unless a timeout value is specified in microseconds of type bigtime_t. A return code of B_ERROR indicates an internal data error and your message is intact. If a reply times out, it will return B_TIMED_OUT. If the target port is invalid, B_BAD_VALUE is returned. Otherwise, it returns B_OK.
 <P>
 <i>Reply Protocol:</i> The target will receive the message with all attached data with one slight modification to the otherwise chosen message protocol - the first item will be a port_id which is the port to which the sender is to reply. All other attached data (if any) immediately follows this port id.
 </li>

headers/private/app/PortLink.h

@@ -14,29 +14,40 @@ class PortLinkData;
 
 class PortLink
 {
+	typedef struct
+	{
+		int32 code;
+		ssize_t buffersize;
+		int8 *buffer;
+		
+	} ReplyData;
 public:
 	PortLink(port_id port);
+	PortLink(const PortLink &link);
 	~PortLink(void);
 	void SetOpCode(int32 code);
 	void SetPort(port_id port);
 	port_id GetPort(void);
-	void Flush(bigtime_t timeout=B_INFINITE_TIMEOUT);
+	status_t Flush(bigtime_t timeout=B_INFINITE_TIMEOUT);
 	int8* FlushWithReply(int32 *code, status_t *status, ssize_t *buffersize,
 		bigtime_t timeout=B_INFINITE_TIMEOUT);
-	void Attach(void *data, size_t size);
-	void Attach(int32 data);
-	void Attach(int16 data);
-	void Attach(int8 data);
-	void Attach(float data);
-	void Attach(bool data);
-	void Attach(BRect data);
-	void Attach(BPoint data);
+	status_t FlushWithReply(PortLink::ReplyData *data,bigtime_t timeout=B_INFINITE_TIMEOUT);
+	status_t Attach(void *data, size_t size);
+	status_t Attach(int32 data);
+	status_t Attach(int16 data);
+	status_t Attach(int8 data);
+	status_t Attach(float data);
+	status_t Attach(bool data);
+	status_t Attach(BRect data);
+	status_t Attach(BPoint data);
 	void MakeEmpty(void);
 protected:	
 	void FlattenData(int8 **buffer,int32 *size);
 	port_id target, replyport;
-	int32 	opcode, bufferlength;
+	int32 opcode;
+	uint32 bufferlength,capacity;
 	int		num_attachments;
+	bool port_ok;
 	PortLinkData *attachments[_PORTLINK_MAX_ATTACHMENTS];
 };
 

src/kits/app/PortLink.cpp

@@ -18,6 +18,8 @@ replyport	- port used with synchronous messaging - FlushWithReply()
 bufferlength - total bytes taken up by attachments
 num_attachments	- internal variable which is used to track which "slot"
 					will be the next one to receive an attachment object
+port_ok - flag to signal whether it's ok to send a message
+capacity - contains the storage capacity of the target port.
 */
 
 #include "PortLink.h"
@@ -35,7 +37,7 @@ class PortLinkData
 public:
 	PortLinkData(void);
 	~PortLinkData(void);
-	bool Set(void *data, size_t size);
+	status_t Set(void *data, size_t size);
 	char *buffer;
 	size_t buffersize;
 };
@@ -45,12 +47,33 @@ PortLink::PortLink(port_id port)
 	// For this class to be useful (and to prevent a lot of init problems)
 	// we require a port in the constructor
 	target=port;
+	port_info pi;
+	port_ok=(get_port_info(target,&pi)==B_OK)?true:false;
+	capacity=pi.capacity;
 	
 	// We start out without any data attached to the port message
 	num_attachments=0;
 	opcode=0;
 	bufferlength=0;
 	replyport=create_port(30,"PortLink reply port");
+	
+	// TODO: initialize all attachments pointers to NULL
+}
+
+PortLink::PortLink(const PortLink &link)
+{
+	// The copy constructor copies everything except a PortLink's attachments. If there
+	// is some reason why someday I might need to change this behavior, I will, but
+	// for now there is no real reason I can think of.
+	target=link.target;
+	opcode=link.opcode;
+	port_ok=link.port_ok;
+	capacity=link.capacity;
+	bufferlength=0;
+	num_attachments=0;
+	replyport=create_port(30,"PortLink reply port");
+
+	// TODO: initialize all attachments pointers to NULL
 }
 
 PortLink::~PortLink(void)
@@ -60,6 +83,9 @@ PortLink::~PortLink(void)
 	// because the port may no longer be valid in cases such as the app
 	// is in the process of quitting
 	MakeEmpty();
+	
+	//TODO: Inline the MakeEmpty call in a way such that it ignores num_attachments
+	// and deletes all non-NULL pointers, setting them to NULL afterward.
 }
 
 void PortLink::SetOpCode(int32 code)
@@ -74,6 +100,9 @@ void PortLink::SetPort(port_id port)
 	// Sets the target port. While not necessary in most uses, this exists
 	// mostly to prevent flexibility problems
 	target=port;
+	port_info pi;
+	port_ok=(get_port_info(target,&pi)==B_OK)?true:false;
+	capacity=pi.capacity;
 }
 
 port_id PortLink::GetPort(void)
@@ -82,13 +111,15 @@ port_id PortLink::GetPort(void)
 	return target;
 }
 
-void PortLink::Flush(bigtime_t timeout=B_INFINITE_TIMEOUT)
+status_t PortLink::Flush(bigtime_t timeout=B_INFINITE_TIMEOUT)
 {
-	// Fires a message off to the target, complete with attachments. NOTE:
-	// the recipient must delete all attachments, being the PortLink object assumes
-	// no responsiblity for the attachments once the message is sent. 
+	// Fires a message off to the target, complete with attachments.
 	int8 *msgbuffer;
 	int32 size;
+	status_t write_stat=B_OK;
+	
+	if(!port_ok)
+		return B_BAD_VALUE;
 
 	if(num_attachments>0)
 	{
@@ -96,27 +127,25 @@ void PortLink::Flush(bigtime_t timeout=B_INFINITE_TIMEOUT)
 		
 		// Dump message to port, reset attachments, and clean up
 		if(timeout!=B_INFINITE_TIMEOUT)
-			write_port_etc(target,opcode,msgbuffer,size,B_TIMEOUT, timeout);
+			write_stat=write_port_etc(target,opcode,msgbuffer,size,B_TIMEOUT, timeout);
 		else
-			write_port(target,opcode,msgbuffer,size);
+			write_stat=write_port(target,opcode,msgbuffer,size);
 		MakeEmpty();
 	}
 	else
 	{
 		if(timeout!=B_INFINITE_TIMEOUT)
-			write_port_etc(target,opcode,NULL,0,B_TIMEOUT, timeout);
+			write_stat=write_port_etc(target,opcode,NULL,0,B_TIMEOUT, timeout);
 		else
-			write_port(target,opcode,NULL,0);
+			write_stat=write_port(target,opcode,NULL,0);
 	}
+	return write_stat;
 }
 
+
 int8* PortLink::FlushWithReply(int32 *code, status_t *status, ssize_t *buffersize, bigtime_t timeout=B_INFINITE_TIMEOUT)
 {
-	// Fires a message to the target and then waits for a reply. The target will
-	// receive a message with the first item being the port_id to reply to.
-	// NOTE: like Flush(), any attached data must be deleted.
-
-	// Effectively, an Attach() call inlined for changes
+	// Deprecated call which functions exactly like PortLink(PortLink::ReplyData *data)
 
 	if(num_attachments>=_PORTLINK_MAX_ATTACHMENTS)
 	{
@@ -124,9 +153,15 @@ int8* PortLink::FlushWithReply(int32 *code, status_t *status, ssize_t *buffersiz
 		return NULL;
 	}
 
+	if(!port_ok)
+	{
+		*status=B_BAD_VALUE;
+		return NULL;
+	}
+
 	// create a new storage object and stash the data
 	PortLinkData *pld=new PortLinkData;
-	if(pld->Set(&replyport,sizeof(port_id)))
+	if(pld->Set(&replyport,sizeof(port_id))==B_OK)
 	{
 		bufferlength+=sizeof(port_id);
 	}
@@ -187,7 +222,82 @@ int8* PortLink::FlushWithReply(int32 *code, status_t *status, ssize_t *buffersiz
 	return buffer;
 }
 
-void PortLink::Attach(void *data, size_t size)
+
+// TODO: write test code
+status_t PortLink::FlushWithReply(PortLink::ReplyData *data,bigtime_t timeout=B_INFINITE_TIMEOUT)
+{
+	// Fires a message to the target and then waits for a reply. The target will
+	// receive a message with the first item being the port_id to reply to.
+	// NOTE: like Flush(), any attached data must be deleted.
+
+	// Effectively, an Attach() call inlined for changes
+
+	if(num_attachments>=_PORTLINK_MAX_ATTACHMENTS)
+		return B_ERROR;
+
+	if(!port_ok)
+		return B_BAD_VALUE;
+
+	// create a new storage object and stash the data
+	PortLinkData *pld=new PortLinkData;
+	if(pld->Set(&replyport,sizeof(port_id)))
+	{
+		bufferlength+=sizeof(port_id);
+	}
+	else
+	{
+		delete pld;
+		return B_ERROR;
+	}
+
+	// Flatten() inlined to make some necessary changes
+	int8 *buffer=new int8[bufferlength];
+	int8 *bufferindex=buffer;
+	size_t size=0;
+
+	// attach our port_id first
+	memcpy(bufferindex, pld->buffer, pld->buffersize);
+	bufferindex += pld->buffersize;
+	size+=pld->buffersize;
+
+	// attach everything else
+	for(int i=0;i<num_attachments;i++)
+	{
+		pld=attachments[i];
+		memcpy(bufferindex, pld->buffer, pld->buffersize);
+		bufferindex += pld->buffersize;
+		size+=pld->buffersize;
+	}
+
+	// Flush the thing....FOOSH! :P
+	write_port(target,opcode,buffer,size);
+	MakeEmpty();
+	delete buffer;
+	
+	// Now we wait for the reply
+	if(timeout==B_INFINITE_TIMEOUT)
+	{
+		data->buffersize=port_buffer_size(replyport);
+		if(data->buffersize>0)
+			data->buffer=(int8*)new int8[data->buffersize];
+		read_port(replyport,&(data->code),&(data->buffer), data->buffersize);
+	}
+	else
+	{
+		data->buffersize=port_buffer_size_etc(replyport,0,timeout);
+		if(data->buffersize==B_TIMED_OUT)
+			return B_TIMED_OUT;
+
+		if(data->buffersize>0)
+			data->buffer=(int8*)new int8[data->buffersize];
+		read_port(replyport,&(data->code),&(data->buffer), data->buffersize);
+	}
+
+	// We got this far, so we apparently have some data
+	return B_OK;
+}
+
+status_t PortLink::Attach(void *data, size_t size)
 {
 	// This is the member called to attach data to a message. Attachments are
 	// treated to be in 'Append' mode, tacking on each attached piece of data
@@ -195,10 +305,13 @@ void PortLink::Attach(void *data, size_t size)
 	
 	// Prevent parameter problems
 	if(num_attachments>=_PORTLINK_MAX_ATTACHMENTS)
-		return;
+		return B_ERROR;
 
 	if(size==0)
-		return;
+		return B_ERROR;
+	
+	if(bufferlength+size>capacity)
+		return B_NO_MEMORY;
 
 	// create a new storage object and stash the data
 	PortLinkData *pld=new PortLinkData;
@@ -212,18 +325,22 @@ void PortLink::Attach(void *data, size_t size)
 	{
 		delete pld;
 	}
+	return B_OK;
 }
 
 // These functions were added for a major convenience in passing common types
 // Eventually, I'd like to templatize these, but for now, this'll do
 
-void PortLink::Attach(int32 data)
+status_t PortLink::Attach(int32 data)
 {
 	// Prevent parameter problems
 	if(num_attachments>=_PORTLINK_MAX_ATTACHMENTS)
-		return;
+		return B_ERROR;
 
 	int32 size=sizeof(int32);
+
+	if(bufferlength+size>capacity)
+		return B_NO_MEMORY;
 	
 	// create a new storage object and stash the data
 	PortLinkData *pld=new PortLinkData;
@@ -237,15 +354,19 @@ void PortLink::Attach(int32 data)
 	{
 		delete pld;
 	}
+	return B_OK;
 }
 
-void PortLink::Attach(int16 data)
+status_t PortLink::Attach(int16 data)
 {
 	// Prevent parameter problems
 	if(num_attachments>=_PORTLINK_MAX_ATTACHMENTS)
-		return;
+		return B_ERROR;
 
 	int32 size=sizeof(int16);
+
+	if(bufferlength+size>capacity)
+		return B_NO_MEMORY;
 	
 	// create a new storage object and stash the data
 	PortLinkData *pld=new PortLinkData;
@@ -259,15 +380,19 @@ void PortLink::Attach(int16 data)
 	{
 		delete pld;
 	}
+	return B_OK;
 }
 
-void PortLink::Attach(int8 data)
+status_t PortLink::Attach(int8 data)
 {
 	// Prevent parameter problems
 	if(num_attachments>=_PORTLINK_MAX_ATTACHMENTS)
-		return;
+		return B_ERROR;
 
 	int32 size=sizeof(int8);
+
+	if(bufferlength+size>capacity)
+		return B_NO_MEMORY;
 	
 	// create a new storage object and stash the data
 	PortLinkData *pld=new PortLinkData;
@@ -281,15 +406,19 @@ void PortLink::Attach(int8 data)
 	{
 		delete pld;
 	}
+	return B_OK;
 }
 
-void PortLink::Attach(float data)
+status_t PortLink::Attach(float data)
 {
 	// Prevent parameter problems
 	if(num_attachments>=_PORTLINK_MAX_ATTACHMENTS)
-		return;
+		return B_ERROR;
 
 	int32 size=sizeof(float);
+
+	if(bufferlength+size>capacity)
+		return B_NO_MEMORY;
 	
 	// create a new storage object and stash the data
 	PortLinkData *pld=new PortLinkData;
@@ -303,15 +432,19 @@ void PortLink::Attach(float data)
 	{
 		delete pld;
 	}
+	return B_OK;
 }
 
-void PortLink::Attach(bool data)
+status_t PortLink::Attach(bool data)
 {
 	// Prevent parameter problems
 	if(num_attachments>=_PORTLINK_MAX_ATTACHMENTS)
-		return;
+		return B_ERROR;
 
 	int32 size=sizeof(bool);
+
+	if(bufferlength+size>capacity)
+		return B_NO_MEMORY;
 	
 	// create a new storage object and stash the data
 	PortLinkData *pld=new PortLinkData;
@@ -325,15 +458,19 @@ void PortLink::Attach(bool data)
 	{
 		delete pld;
 	}
+	return B_OK;
 }
 
-void PortLink::Attach(BRect data)
+status_t PortLink::Attach(BRect data)
 {
 	// Prevent parameter problems
 	if(num_attachments>=_PORTLINK_MAX_ATTACHMENTS)
-		return;
+		return B_ERROR;
 
 	int32 size=sizeof(BRect);
+
+	if(bufferlength+size>capacity)
+		return B_NO_MEMORY;
 	
 	// create a new storage object and stash the data
 	PortLinkData *pld=new PortLinkData;
@@ -347,15 +484,19 @@ void PortLink::Attach(BRect data)
 	{
 		delete pld;
 	}
+	return B_OK;
 }
 
-void PortLink::Attach(BPoint data)
+status_t PortLink::Attach(BPoint data)
 {
 	// Prevent parameter problems
 	if(num_attachments>=_PORTLINK_MAX_ATTACHMENTS)
-		return;
+		return B_ERROR;
 
 	int32 size=sizeof(BPoint);
+
+	if(bufferlength+size>capacity)
+		return B_NO_MEMORY;
 	
 	// create a new storage object and stash the data
 	PortLinkData *pld=new PortLinkData;
@@ -369,6 +510,7 @@ void PortLink::Attach(BPoint data)
 	{
 		delete pld;
 	}
+	return B_OK;
 }
 
 void PortLink::FlattenData(int8 **buffer,int32 *size)
@@ -413,26 +555,27 @@ PortLinkData::PortLinkData(void)
 {
 	// Initialize object to empty
 	buffersize=0;
+	buffer=NULL;
 }
 
 PortLinkData::~PortLinkData(void)
 {
 	// Frees the buffer if we actually used the class to store data
-	if(buffersize>0)
+	if(buffersize>0 && buffer!=NULL)
 		free(buffer);
 }
 
-bool PortLinkData::Set(void *data, size_t size)
+status_t PortLinkData::Set(void *data, size_t size)
 {
 	// Function copies the passed to the internal buffers for storage
 	if(size>0 && buffersize==0 && data!=NULL)
 	{
 		buffer=(char *)malloc(size);
 		if(buffer==NULL)
-			return false;
+			return B_NO_MEMORY;
 		memcpy(buffer, data, size);
 		buffersize=size;
-		return true;
+		return B_OK;
 	}
-	return false;
+	return B_ERROR;
 }