Path: utzoo!utgpu!water!watmath!clyde!att!osu-cis!tut.cis.ohio-state.edu!mailrus!cornell!rochester!rutgers!apple!voder!pyramid!oliveb!amiga!jimm From: jimm@amiga.UUCP (Jim Mackraz) Newsgroups: comp.sys.amiga.tech Subject: Shared IDCMP Ports--Proposal Message-ID: <3031@amiga.UUCP> Date: 18 Oct 88 01:23:53 GMT Reply-To: jimm@amiga.UUCP (Jim Mackraz) Organization: Commodore-Amiga Inc, Los Gatos CA Lines: 201 ----- 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.