Exec Messages and Ports - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:40:03Z

Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

← Older revision		Revision as of 19:40, 26 January 2025
Line 17:		Line 17:
	A message port consists of a MsgPort structure as defined in the <exec/ports.h> and <exec/ports.i> include files. The C structure for a port is as follows:		A message port consists of a MsgPort structure as defined in the <exec/ports.h> and <exec/ports.i> include files. The C structure for a port is as follows:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct MsgPort {		struct MsgPort {
	struct Node mp_Node;		struct Node mp_Node;
Line 77:		Line 77:
	The following is an example of how to safely put a message to a specific port:		The following is an example of how to safely put a message to a specific port:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	#include <exec/types.h>		#include <exec/types.h>
	#include <exec/ports.h>		#include <exec/ports.h>
Line 103:		Line 103:
	As mentioned earlier, a message contains both system header information and the actual message content. The system header is of the Message form defined in <exec/ports.h>. This structure is as follows:		As mentioned earlier, a message contains both system header information and the actual message content. The system header is of the Message form defined in <exec/ports.h>. This structure is as follows:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Message {		struct Message {
	struct Node mn_Node;		struct Node mn_Node;
Line 122:		Line 122:
	This structure is always attached to the head of all messages. For example, if you want a message structure that contains the ''x'' and ''y'' coordinates of a point on the screen, you could define it as follows:		This structure is always attached to the head of all messages. For example, if you want a message structure that contains the ''x'' and ''y'' coordinates of a point on the screen, you could define it as follows:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct XYMessage {		struct XYMessage {
	struct Message xy_Msg;		struct Message xy_Msg;
Line 136:		Line 136:
	Messages are allocated using AllocSysObject() with an object type of ASOT_MESSAGE. The ASOMSG_ReplyPort tag is set to the reply port if desired. Some messages may be sent in one direction in which case the ASOMSG_ReplyPort tag is not used. The size of the message is indicated with ASOMSG_Length and includes the size of the payload.		Messages are allocated using AllocSysObject() with an object type of ASOT_MESSAGE. The ASOMSG_ReplyPort tag is set to the reply port if desired. Some messages may be sent in one direction in which case the ASOMSG_ReplyPort tag is not used. The size of the message is indicated with ASOMSG_Length and includes the size of the payload.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct XYMessage xymsg = IExec->AllocSysObjectTags(ASOT_MESSAGE,		struct XYMessage xymsg = IExec->AllocSysObjectTags(ASOT_MESSAGE,
	ASOMSG_Size, sizeof(struct XYMessage),		ASOMSG_Size, sizeof(struct XYMessage),
Line 153:		Line 153:
	Here is a code fragment for putting a message to a public port. A complete example is at the end of the article.		Here is a code fragment for putting a message to a public port. A complete example is at the end of the article.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	#include <exec/types.h>		#include <exec/types.h>
	#include <exec/memory.h>		#include <exec/memory.h>
Line 217:		Line 217:
	You can call the WaitPort() function to wait for a message to arrive at a port. This function will return the first message (it may not be the only) queued to a port. Note that your application must still call GetMsg() to remove the message from the port. If the port is empty, your task will go to sleep waiting for the first message. If the port is not empty, your task will not go to sleep. It is possible to receive a signal for a port without a message being present yet. The code processing the messages should be able to handle this. The following code illustrates WaitPort().		You can call the WaitPort() function to wait for a message to arrive at a port. This function will return the first message (it may not be the only) queued to a port. Note that your application must still call GetMsg() to remove the message from the port. If the port is empty, your task will go to sleep waiting for the first message. If the port is not empty, your task will not go to sleep. It is possible to receive a signal for a port without a message being present yet. The code processing the messages should be able to handle this. The following code illustrates WaitPort().

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct MsgPort *xyport = IExec->AllocSysObjectTags(ASOT_PORT,		struct MsgPort *xyport = IExec->AllocSysObjectTags(ASOT_PORT,
	ASOPORT_Name, "xyport",		ASOPORT_Name, "xyport",
Line 235:		Line 235:
	Here's an example using Wait():		Here's an example using Wait():

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct XYMessage *xy_msg;		struct XYMessage *xy_msg;
	BOOL ABORT = FALSE;		BOOL ABORT = FALSE;
Line 274:		Line 274:
	The example below illustrates the use of GetMsg() to print the contents of all messages in a port:		The example below illustrates the use of GetMsg() to print the contents of all messages in a port:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	while (xymsg = IExec->GetMsg(xyport))		while (xymsg = IExec->GetMsg(xyport))
	IDOS->Printf("x=%ld y=%ld\n", xymsg->xy_X, xymsg->xy_Y);		IDOS->Printf("x=%ld y=%ld\n", xymsg->xy_X, xymsg->xy_Y);
Line 289:		Line 289:
	The previous example can be enhanced to reply to each of its messages:		The previous example can be enhanced to reply to each of its messages:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	while (xymsg = IExec->GetMsg(xyport)) {		while (xymsg = IExec->GetMsg(xyport)) {
	IDOS->Printf("x=%ld y=%ld\n", xymsg->xy_X, xymsg->xy_Y);		IDOS->Printf("x=%ld y=%ld\n", xymsg->xy_X, xymsg->xy_Y);
Line 304:		Line 304:
	==== Port1.c ====		==== Port1.c ====

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	// port1.c - port and message example, run at the same time as port2.c		// port1.c - port and message example, run at the same time as port2.c

Line 371:		Line 371:
	==== Port2.c ====		==== Port2.c ====

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	// port2.c - port and message example, run at the same time as port1.c		// port2.c - port and message example, run at the same time as port1.c

Frédéric Khannouf: /* Port2.c */ Put ASOT_Message in upper case

2021-01-21T22:36:32Z

Port2.c: Put ASOT_Message in upper case

← Older revision		Revision as of 22:36, 21 January 2021
Line 423:		Line 423:
	}		}
	else IDOS->Printf("Can't find 'xyport'; start port1 in a separate shell\n");		else IDOS->Printf("Can't find 'xyport'; start port1 in a separate shell\n");
	IExec->FreeSysObject(~~ASOT_Message~~, xymsg);		IExec->FreeSysObject(ASOT_MESSAGE, xymsg);
	}		}
	else IDOS->Printf("Couldn't get memory\n");		else IDOS->Printf("Couldn't get memory\n");

Frédéric Khannouf: /* Port2.c */ Added missing IExec-> to FindPort call

2021-01-21T22:15:20Z

Port2.c: Added missing IExec-> to FindPort call

← Older revision		Revision as of 22:15, 21 January 2021
Line 435:		Line 435:
	{		{
	IExec->Forbid();		IExec->Forbid();
	struct MsgPort *port = FindPort(portname);		struct MsgPort *port = IExec->FindPort(portname);
	if (port != NULL) IExec->PutMsg(port, message);		if (port != NULL) IExec->PutMsg(port, message);
	IExec->Permit();		IExec->Permit();

Frédéric Khannouf: /* Replying */

2019-03-26T13:22:24Z

Replying

← Older revision		Revision as of 13:22, 26 March 2019
Line 298:		Line 298:
	Notice that the reply does not occur until ''after'' the message values have been used.		Notice that the reply does not occur until ''after'' the message values have been used.

	Often the operations associated with receiving a message involve returning ''results'' to the originator. Typically this is done within the message itself. The receiver places the results in fields defined (or perhaps reused) within the message body before replying the message back to the originator. Receipt of the replied message at the ~~originator‚Äôs~~ reply port indicates it is once again safe for the originator to use or change the values found within the message.		Often the operations associated with receiving a message involve returning ''results'' to the originator. Typically this is done within the message itself. The receiver places the results in fields defined (or perhaps reused) within the message body before replying the message back to the originator. Receipt of the replied message at the originator reply port indicates it is once again safe for the originator to use or change the values found within the message.

	The following are two short example tasks that communicate by sending, waiting for and replying to messages. Run these two programs together.		The following are two short example tasks that communicate by sending, waiting for and replying to messages. Run these two programs together.

Steven Solie: /* Waiting for a Message */

2015-11-03T23:07:49Z

Waiting for a Message

← Older revision		Revision as of 23:07, 3 November 2015
Line 231:		Line 231:
	</syntaxhighlight>		</syntaxhighlight>

	A more general form of waiting for a message involves the use of the Wait() function (see ~~the "~~Exec Signals~~" chapter~~). This function waits for task event signals directly. If the signal assigned to the message port occurs, the task will awaken. Using the Wait() function is more general because you can wait for more than one signal. By combining the signal bits from each port into one mask for the Wait() function, a loop can be set up to process all messages at all ports.		A more general form of waiting for a message involves the use of the Wait() function (see [[Exec_Signals\|Exec Signals]]). This function waits for task event signals directly. If the signal assigned to the message port occurs, the task will awaken. Using the Wait() function is more general because you can wait for more than one signal. By combining the signal bits from each port into one mask for the Wait() function, a loop can be set up to process all messages at all ports.

	Here's an example using Wait():		Here's an example using Wait():

Steven Solie: /* Putting a Message */

2015-11-03T23:07:06Z

Putting a Message

← Older revision		Revision as of 23:07, 3 November 2015
Line 151:		Line 151:
	A message is delivered to a given destination port with the PutMsg() function. The message is queued to the port, and that port's arrival action is invoked. If the action specifies a task signal or a software interrupt, the originating task may temporarily lose the processor while the destination processes the message. If a reply to the message is required, the mn_ReplyPort field must be set up prior to the call to PutMsg().		A message is delivered to a given destination port with the PutMsg() function. The message is queued to the port, and that port's arrival action is invoked. If the action specifies a task signal or a software interrupt, the originating task may temporarily lose the processor while the destination processes the message. If a reply to the message is required, the mn_ReplyPort field must be set up prior to the call to PutMsg().

	Here is a code fragment for putting a message to a public port. A complete example is ~~printed~~ at the end of the ~~chapter~~.		Here is a code fragment for putting a message to a public port. A complete example is at the end of the article.

	<syntaxhighlight>		<syntaxhighlight>

Steven Solie: /* Putting a Message */

2013-05-08T19:24:55Z

Putting a Message

← Older revision		Revision as of 19:24, 8 May 2013
Line 159:		Line 159:
	#include <libraries/dos.h>		#include <libraries/dos.h>

	int main();
	BOOL SafePutToPort(struct Message *, CONST_STRPTR);		BOOL SafePutToPort(struct Message *, CONST_STRPTR);

Line 205:		Line 204:
	}		}
	else IDOS->Printf("Couldn't get memory for xymessage\n");		else IDOS->Printf("Couldn't get memory for xymessage\n");

			return 0;
	}		}
	</syntaxhighlight>		</syntaxhighlight>

Steven Solie: /* Waiting for a Message */

2012-07-12T19:59:04Z

Waiting for a Message

← Older revision		Revision as of 19:59, 12 July 2012
Line 212:		Line 212:
	A task may go to sleep waiting for a message to arrive at one or more ports. This technique is widely used on the Amiga as a general form of event notification. For example, it is used extensively by tasks for I/O request completion.		A task may go to sleep waiting for a message to arrive at one or more ports. This technique is widely used on the Amiga as a general form of event notification. For example, it is used extensively by tasks for I/O request completion.

	The MsgPort.mp_SigTask field contains the address of the task to be signaled and mp_SigBit contains a preallocated signal number (as described in ~~the "~~Exec Tasks~~" chapter~~).		The MsgPort.mp_SigTask field contains the address of the task to be signaled and mp_SigBit contains a preallocated signal number (as described in [[Exec_Tasks\|Exec Tasks]]).

	You can call the WaitPort() function to wait for a message to arrive at a port. This function will return the first message (it may not be the only) queued to a port. Note that your application must still call GetMsg() to remove the message from the port. If the port is empty, your task will go to sleep waiting for the first message. If the port is not empty, your task will not go to sleep. It is possible to receive a signal for a port without a message being present yet. The code processing the messages should be able to handle this. The following code illustrates WaitPort().		You can call the WaitPort() function to wait for a message to arrive at a port. This function will return the first message (it may not be the only) queued to a port. Note that your application must still call GetMsg() to remove the message from the port. If the port is empty, your task will go to sleep waiting for the first message. If the port is not empty, your task will not go to sleep. It is possible to receive a signal for a port without a message being present yet. The code processing the messages should be able to handle this. The following code illustrates WaitPort().
Line 265:		Line 265:
	</syntaxhighlight>		</syntaxhighlight>

		⚫	{{Note\|text=WaitPort() only returns a pointer to the first message in a port. It does not actually remove the message from the port queue.\|title=WaitPort() Does Not Remove A Message}}
	{\| class="wikitable"
⚫	\| ~~''WaitPort() Does Not Remove A Message''.~~ WaitPort() only returns a pointer to the first message in a port. It does not actually remove the message from the port queue.
	\|}

	=== Getting a Message ===		=== Getting a Message ===

Steven Solie at 15:39, 21 June 2012

2012-06-21T15:39:05Z

← Older revision		Revision as of 15:39, 21 June 2012
Line 1:		Line 1:
	{{CodeReview}}
	== Exec Messages and Ports ==		== Exec Messages and Ports ==

Steven Solie: /* Port1.c */

2012-06-21T15:38:27Z

Port1.c

← Older revision		Revision as of 15:38, 21 June 2012
Line 325:		Line 325:
	BOOL ABORT = FALSE;		BOOL ABORT = FALSE;

	struct MsgPort *xyport = IExec->AllocSysObjectTags(ASOT_PORT, ~~TAG_END);~~		struct MsgPort *xyport = IExec->AllocSysObjectTags(ASOT_PORT,
			ASOPORT_Name, "xyport",
			TAG_END);

	if (xyport != NULL)		if (xyport != NULL)
	{		{