The Mailslot class

class Mailslot(name, serialiser=(<function _unserialised at 0x034F2CF0>, <function _unserialised at 0x034F2CF0>), message_size=0, timeout_ms=-1, *args, **kwargs)

Bases: winsys.core._WinSysObject

A mailslot is a mechanism for passing small datasets (up to about 400 bytes) between machines in the same network. For transport and name resolution it uses NetBIOS so you can’t, for example, use a machine’s IP address when specifying the location of a mailslot. You can, however, use “*” in order to broadcast your message to all listening machines.

A mailslot is either read-only or write-only. The typical case is that one machine starts up a reading mailslot, say for trace output, and all other machines write to that mailslot either by specifying the machine name directly or by broadcasting. This is particularly convenient as the writing machines have no need to determine where the trace-collecting mailslot is running or even if it is running at all.

The format for mailslot names is \\<computer>\mailslot\<path>\<to>\<mailslot> The computer name can be ”.” for the local computer, a Windows computer name, a domain name, or an asterisk to indicate a broadcast. It’s not necessary to have a complex path for the mailslot but it is supported and could be used to segregate functionally similar mailslots on the same or different machines.

This class deliberately wraps the mailslot API in a Python API which is plug-compatible with that of the Python Queue mechanism with the following notes:

• A mailslot is either read-only or write-only. Generally, the first action taken on it determines which it is, although remote mailslots can only be written to so this is predetermined.
• A mailslot can be context-managed so that it is opened and closed correctly regardless of any errors.
• A mailslot is its own iterator (strictly: generator)
• By default the data through a mailslot is expected to be text, and is passed through untouched. Alternative serialisers can be provided, for example marshal.dumps and marshal.loads to allow simple objects to be transmitted via the mailslot. Note that the maximum message size still applies so it’s not possible to send very complex datasets this way.

Since a mailslot will always return immediately if passed to one of the Wait... functions, events or other synchronisation objects will be needed to coordinate between mailslots.

Set up a mailslot of the given name, which must be valid according to the Microsoft docs.

Parameters:

• serialiser (a pair of callables each taking one param and returning bytes) – a pair of callable which will be used to encode & decode data respectively. Typical serialisers would be (marshal.dumps, marshal.loads).
• message_size – the maximum size of a message to this mailslot, up to the system-defined maximum of about 400 bytes if passing between computers.
• timeout_ms – how many milliseconds to wait when reading from this mailslot

as_string()

close()

Close the mailslot for reading or writing. This will be called automatically if the mailslot is being context-managed. Closing a mailslot which has not been used (and which therefore has no open handles) will succeed silently.

dumped(level=0)

empty()

Returns:True if there is nothing waiting to be read

full()

Returns:True if the number of messages waiting to be read has reached the maximum size for the mailslot

get(block=True, timeout_ms=None)

Attempt to read from the mailslot, optionally blocking and timing out if nothing is found.

Parameters:

• block – whether to wait timeout_ms milliseconds before raising x_mailslot_empty
• timeout_ms – how many milliseconds to wait before timing out if blocking. None => wait forever

Returns:

the first message from the mailslot queue serialised according to the class’s serialiser

Raises :

x_mailslot_empty if timed out or unblocked

get_nowait()

Convenience wrapper which calls get() without blocking

put(data)

Attempt to write to the mailslot

Parameters:data – data to be written to the mailslot via its serialisers Raises :x_mailslot_message_too_big if the serialised message exceeds the mailslot’s maximum size

pyobject()

Returns:the underlying PyHANDLE object Raises :x_mailslot if the mailslot has not yet been determined for reading or for writing

qsize()

Returns:the number of messages waiting in the mailslot