ipc – Interprocess Communication

Introduction

The IPC module offers an interface to the various forms of interprocess communication available under windows: mailslots, events, named pipes, mutexes, sempahores and waitable timers. At least, that’s the plan. At the time of writing, only mailslots and events are in there. But the rest are definitely on the way.

Functions

Factories

mailslot(mailslot, marshalled=True, message_size=0, timeout_ms=-1)

Return a Mailslot instance based on the name in mailslot. If the name is not a fully-qualified mailslot name (\.mailslot) then it is assumed to be on the local machine and is prefixed accordingly.

Parameters:

• mailslot – a valid mailslot name, with the convenience that if it is unqualified it is suitably prefixed to form a local mailslot identifier.
• marshalled – whether the data is to be marshalled or simply passed along unchanged.
• message_size – what message should be used; 0 to use the system default
• timeout_ms – how many milliseconds should a read wait before giving up? -1 to wait forever.

event(name=None, initially_set=False, needs_manual_reset=False, security=None)

Return a Event instance, named or anonymous, unset by default and with automatic reset.

Parameters:

• name – a valid event name. If None (the default) then an anonymous event is created which may be passed to threads which need to synchronise.
• initially_set – whether the event is set on creation. [False]
• needs_manual_reset – whether the event needs to be reset manually once it has fired. The alternative is that, once the event has fired, it falls back to an unset state.
• security (anything accepted by security.security()) – what security to apply to the new event

Returns:

a Event instance

mutex(name=None, take_initial_ownership=False)

Return a Mutex instance, named or anonymous, not initially owned by default.

Parameters:

• name – a valid mutex name. If None (the default) then an anonymous mutex is created which may be passed to threads which need to synchronise.
• take_initial_ownership – whether the mutex just created is to be owned by the creating thread.

Returns:

a Mutex instance

pipe(name=None)

Return a pipe. If name is given a NamedPipe is returned, otherwise an AnonymousPipe. If name is not in the correct form for a pipe (\\<machine>\pipe\<name>) it is assumed to be a local pipe and renamed as such.

Helpers

any(objects, timeout_ms=-1)

Wait for any of the Windows synchronisation objects in the list to fire. The objects must be winsys synchronisation objects (or, at least, have a pyobject method which returns a PyHANDLE object). The one which fires will be returned unless a timeout occurs in which case x_ipc_timeout will be raised.

Parameters:

• objects – an iterable of winsys objects each of which has a waitable handle
• timeout_ms – how many milliseconds to wait

Returns:

the object which fired

Raises :

x_ipc_timeout if timeout_ms is exceeded

all(objects, timeout_ms=-1)

Wait for all of the Windows synchronisation objects in the list to fire. The objects must be winsys synchronisation objects (or, at least, have a pyobject method which returns a PyHANDLE object).

Parameters:

• objects – an iterable of winsys objects each of which has a waitable handle
• timeout_ms – how many milliseconds to wait

Raises :

x_ipc_timeout if timeout_ms is exceeded

Classes

• The Mailslot class
• The Event class
• The Mutex class
• The Pipe classes

Constants

WAIT

Name	Val	Win32
FAILED	-1	INFINITE
INFINITE	-1	INFINITE
OBJECT_0	0	WAIT_OBJECT_0
ABANDONED	128	WAIT_ABANDONED_0
ABANDONED_0	128	WAIT_ABANDONED_0
IO_COMPLETION	192	WAIT_IO_COMPLETION
TIMEOUT	258	WAIT_TIMEOUT

Exceptions

exception x_ipc(errno=None, errctx=None, errmsg=None)

exception x_mailslot(errno=None, errctx=None, errmsg=None)

exception x_mailslot_invalid_use(errno=None, errctx=None, errmsg=None)

exception x_mailslot_empty(errno=None, errctx=None, errmsg=None)

exception x_mailslot_message_too_big(errno=None, errctx=None, errmsg=None)

exception x_mailslot_message_too_complex(errno=None, errctx=None, errmsg=None)

References

See also

Synchronisation

Documentation on microsoft.com for synchronisation objects

Using the ipc module

Cookbook examples of using the ipc module

To Do

• Named Pipes
• Waitable Timers
• Waits