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

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

Table Of Contents

Previous topic

fs Constants

Next topic

The Mailslot class

This Page