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

ipc.mailslot(mailslot, marshalled=True, message_size=0, timeout_ms=-1)[source]

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.
ipc.event(name=None, initially_set=False, needs_manual_reset=False, security=None)[source]

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

ipc.mutex(name=None, take_initial_ownership=False)[source]

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

ipc.pipe(name=None)[source]

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

ipc.any(objects, timeout_ms=-1)[source]

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

ipc.all(objects, timeout_ms=-1)[source]

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

ipc.WAIT = <Constants: {'ABANDONED': 128, 'ABANDONED_0': 128, 'IO_COMPLETION': 192, 'OBJECT_0': 0, 'FAILED': -1, 'TIMEOUT': 258, 'INFINITE': -1}>
Name Val Win32
OBJECT_0 0x00000000 WAIT_OBJECT_0
ABANDONED 0x00000080 WAIT_ABANDONED_0
ABANDONED_0 0x00000080 WAIT_ABANDONED_0
IO_COMPLETION 0x000000C0 WAIT_IO_COMPLETION
TIMEOUT 0x00000102 WAIT_TIMEOUT
FAILED 0xFFFFFFFF INFINITE
INFINITE 0xFFFFFFFF INFINITE

Exceptions

exception ipc.x_ipc(errno=None, errctx=None, errmsg=None)[source]
exception ipc.x_mailslot(errno=None, errctx=None, errmsg=None)[source]
exception ipc.x_mailslot_invalid_use(errno=None, errctx=None, errmsg=None)[source]
exception ipc.x_mailslot_empty(errno=None, errctx=None, errmsg=None)[source]
exception ipc.x_mailslot_message_too_big(errno=None, errctx=None, errmsg=None)[source]
exception ipc.x_mailslot_message_too_complex(errno=None, errctx=None, errmsg=None)[source]

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