🚀 go-pugleaf

	----- Shared IDCMP Ports -----

    At the request of developers, we've tried to develop a standard by
    which users may use their Window IDCMP port for other Inter-Process
    Communication (IPC).

    Here is an explanation of the issues and a tentative proposal.  As
    a developer, your feedback is important and welcome.  Note that
    these standards, when blessed, can be used immediately.  There
    is no need to wait for V1.4 once conventions are established.

	----- IDCMP Basics -----

    The important things about a Window's IDCMP port are how it's created,
    how it's deleted, and what happens in the meantime.

    An IDCMP port (and a freshly allocated signal) is created when you
    open a window with non-zero IDCMPFlags, or when you call ModifyIDCMP
    with non-zero IDCMPFlags and there is no port already.

    An IDCMP port is deleted when you close a window and the IDCMP port
    exists (and is pointed to by Window.UserPort), or if it exists when
    you call ModifyIDCMP with zero IDCMPFlags.  When Intuition closes
    down a port, it assumes that all messages on that port are
    IntuiMessages.  For each message, it removes it from the port,
    sets its IntuiMessage.Code field to OKABORT, and ReplyMsg's it.

    This isn't all that bad.  At least your messages hanging off of
    the IDCMP port will be replied to you.

    We will not guarantee that the OKABORT step will be taken, but you
    cannot count on ANYTHING about the "Code" field of a message being
    replied from an IDCMP port.

    Messages will be sent to an IDCMP port on an unpredictable schedule
    from Intuition.  The primary identification of such messages is
    the first long word, the Class field for IntuiMessages.  We can
    reserve a value for this Class field for non-Intuition traffic.

	----- Sharing Ports, In General -----

    Even were Intuition not in the loop, there are some general problems
    servicing several senders of messages at a single port.  The first
    is identification, and the second is unserviced leftover messages.

    It's easy to agree on a field that will contain an ID which identifies
    which service sent a message, but how are those ID's defined?  We
    propose that they be defined by the receiver program.  That is,
    when you register a port with a message sending service, you will
    specify an ID which you want included in every message that the
    service sends you.  Typically, you will be able to make constant
    assignments for different services without complication.

    The way to handle leftover messages is to reply to all the messages
    sent by a service when you are done with the service.  Note that first
    you must tell the service to stop sending you more messages, the 
    service cannot go away completely (deallocating its reply port) until
    you have replied all the messages, and that you must Forbid or otherwise
    inhibit other services from sending messages to that port if you
    are walking down the message list and selectively replying to messages
    from a particular service.

	----- Specific Proposals for IDCMP Compatible IPC Messages -----

    A service which is sending IPC messages which can be safely received
    at an IDCMP port must follow the following conventions:

    Registration of Port/ID:

	It is assumed that a message sending service is a library or device,
	or a permanent module.  This is so that there is time to reply
	accumulated messages  after you "de-register" your port.  So,
	OpenLibrary or the equivalent guarantees the existence of the
	services reply port until CloseLibrary is called, for example.

	When specifying that you want messages sent to you for some
	reason, you "register" your port with the service, typically
	through a library call.  In so doing, you provide an 8 or
	sixteen bit ID (haven't decided yet).  It is the responsibility
	of the service to keep that ID associated with the port
	you have registered and to copy it into each message (see
	below).

	The ID will need to be copied into each message every time
	it is sent, since it is possible and likely that the ID
	field will be corrupted by the receiver (due to interaction
	with Intuition).  See below for more comments on message format.

    Shut Down:

	There must be a "de-register" function as well, or some other
	method of insuring that no further messages will be sent
	from a given service to a given port.  This function must be
	synchronous: not even one single message must be issued after
	this call has returned.

	It must continue to be safe to ReplyMsg messages sent from
	a service AFTER the port has been de-registered, such as until
	a CloseLibrary call has been made.

    Format:
	The message must begin with a format that mimics the beginning
	of an IDCMP message:

	struct IPCHeader
	{
	    struct Message ExecMessage;
	    ULONG Class;
	    USHORT Code;
	};

	For non-Intuition messages, Class will always be the same value,
	somthing like IDCMPUSER.   Code will contain a copy of the 
	of the registration ID provided above.  We are debating whether
	the ID should be 8 or sixteen bits.  If it is eight, then
	it can be put in the high-order byte of Code accompanied by
	a command code in the low order byte.  This would let people
	write programs with one fewer levels of switch statement.  The 
	downside is that it reduces the ID space to 256 simultaneous
	services.

	Examples:

	/* ID is 16 bits, entire Code field	*/
	switch ( imsg->Class )
	case IDCMPUSER:
	    switch ( imsg->Code )
	    case SERVICEA:
		switch ( imsg->customcommanddata )
		case SERVICEA_COMMAND1:
		case SERVICEA_COMMAND2:

	This could become, with an eight bit ID:

	/* ID is 8 bits, in high byte of Code field	*/
	switch ( imsg->Class )
	case IDCMPUSER:
	    switch ( imsg->Code )
	    case (SERVICEA << 8) | SERVICEA_COMMAND:

    Is it worth it?

	----- Using an IDCMP port for Other Purposes -----

    If you want to use an IDCMP port managed (created, deleted) by
    Intuition, you must take the following steps:

    Once Intuition creates the port (OpenWindow, ModifyIDCMP) register
    the port with the IPC service.  Never let Intuition delete that
    port while it is registered with another service.

    Handle the IDCMPUSER messages as described above.

    When you want the port deleted (CloseWindow, ModifyIDCMP),
    first de-register the port with all services.  Then CloseWindow,
    and lastly close the services libraries.  This sequence insures that
    Intuition's replying of any leftover IDCMPUSER messages will
    send them to a valid port.  A conforming server will not have
    a problem with the fact that Intuition clobbers the Code field
    when it replies messages in these circumstances.

	----- Using a port of your own for IDCMP -----

    This is a little trickier.  The problem is that you don't want
    Intuition to delete your port when you CloseWindow (or ModifyIDCMP),
    so you have to remove it before you shut down the IDCMP traffic.
    But this will prevent Intuition from clearing the traffic (replying
    all your messages) so there may be outstanding IntuiMessages hanging
    off of the port.

    Now if you leave them hanging and close your window, Intuition will
    free their memory, and you will be left with a message chain linked
    through free memory; not a happy situation.

    The way you handle this is to remove the port from the Window
    (Window.UserPort = NULL), ModifyIDCMP(NULL) (Intuition will not try
    to free your NULL port), and while forbidden, walk the message port
    list removing and replying all Intuition messages.  Since you
    have shut off further traffic by ModifyIDCMP, you are now in a safe
    state for calling CloseWindow.

	----- Using a single port for multiple windows -----

    This is simply using your own port for IDCMP, but for more than
    one window.  The sequence of closing a window is the same, but
    you must take care to remove and reply only those IDCMP messages
    which were directed at the window you are trying to close.

    This is done in a demonstration named CloseWindowSafely(), which
    we will repost in a final draft of this standard.  It needs no
    change to support messages arriving at the port from non-Intuition
    IPC services.



-- 
	Jim Mackraz, I and I Computing	  
	amiga!jimm	BIX:jmackraz
Opinions are my own.  Comments regarding the Amiga operating system, and
all others, are not to be taken as Commodore official policy.