efl.ecore.Exe Class

class efl.ecore.Exe(exe_cmd, int flags=0, data=None)

Bases: object

This function forks and runs the given command using /bin/sh.

Note that the process handle is only valid until a child process terminated event is received. After all handlers for the child process terminated event have been called, the handle will be freed by Ecore. In this case the Python wrapper becomes “shallow” and all operations will fail or return bogus/dummy values, although it should not crash.

This class behavior is configurable by means of given constructor flags, that will make Ecore monitor process’ stdout and stderr, emitting events on main loop.

To write use send(). To read listen to ECORE_EXE_EVENT_DATA or ECORE_EXE_EVENT_ERROR events (see below). Ecore may buffer read and error data until a newline character if asked for with the flags. All data will be included in the events (newlines will be replaced with NULLS if line is buffered).

ECORE_EXE_EVENT_DATA events will only happen if the process is run with ECORE_EXE_PIPE_READ enabled in the flags. The same with the error version. Writing will only be allowed with ECORE_EXE_PIPE_WRITE enabled in the flags.

Instance Event Handling

To make use easier, there are methods that automatically filter events for this instance and deletes them when the Exe is deleted:

  • on_add_event_add()
  • on_add_event_del()
  • on_del_event_add()
  • on_del_event_del()
  • on_data_event_add()
  • on_data_event_del()
  • on_error_event_add()
  • on_error_event_del()

The callback signatures are:

func(exe, event, *args, **kargs)

In contrast with C-api conformant functions. This only receives the events from this exact exe instance. The signature is also very different, the first parameter is the Exe reference and the return value does not removes the event listener!

Using this method is likely more efficient than the C-api since it will not convert from C to Python lots of times, possibly useless.

However, there are C-api conformat functions as well.

Event Handling (C-api conformant)

Getting data from executed processed is done by means of event handling, which is also used to notify whenever this process really started or died.

One should listen to events in the main loop, such as:

EventExeAdd
listen with on_exe_add_event_add() to know when sub processes were started and ready to be used.
EventExeDel
listen with on_exe_del_event_add() to know when sub processes died.
EventExeData
listen with on_exe_data_event_add() to know when sub processes output data to their stdout.
EventExeError
listen with on_exe_error_event_add() to know when sub processes output data to their stderr.

Events will have the following signature, as explained in EventHandler:

func(event, *args, **kargs): bool

That mean once registered, your callback func will be called for all known Exe instances (that were created from Python!). You can query which instance created such event with event.exe property. Thus you often need to filter if the event you got is from the instance you need! (This is designed to match C-api).

Once your function returns evaluates to False (note: not returning means returning None, that evaluates to False!), your callback will not be called anymore and your handler is deleted.

One may delete handlers explicitly with EventHandler.delete() method.

Parameters:
  • exe_cmd (str) – command to execute as subprocess.
  • flags (int) –

    if given (!= 0), should be bitwise OR of

    ECORE_EXE_PIPE_READ
    Exe Pipe Read mask
    ECORE_EXE_PIPE_WRITE
    Exe Pipe Write mask
    ECORE_EXE_PIPE_ERROR
    Exe Pipe error mask
    ECORE_EXE_PIPE_READ_LINE_BUFFERED
    Reads are buffered until a newline and delivered 1 event per line.
    ECORE_EXE_PIPE_ERROR_LINE_BUFFERED
    Errors are buffered until a newline and delivered 1 event per line.
    ECORE_EXE_PIPE_AUTO
    stdout and stderr are buffered automatically
    ECORE_EXE_RESPAWN
    Exe is restarted if it dies
    ECORE_EXE_USE_SH
    Use /bin/sh to run the command.
    ECORE_EXE_NOT_LEADER
    Do not use setsid() to have the executed process be its own session leader
  • data – extra data to be associated and available with data_get()
auto_limits_set(start_bytes, end_bytes, start_lines, end_lines)

Sets the auto pipe limits for the given process handle

Parameters:
  • start_bytes – limit of bytes at start of output to buffer.
  • end_bytes – limit of bytes at end of output to buffer.
  • start_lines – limit of lines at start of output to buffer.
  • end_lines – limit of lines at end of output to buffer.
close_stdin()

Close executed process’ stdin.

The stdin of the given child process will not be closed immediately. Instead it will be closed when the write buffer is empty.

cmd_get()

Retrieves the command of the executed process.

Returns:the command line string if execution succeeded, None otherwise.
Return type:str or None
continue_()

Send continue signal (SIGCONT) to executed process.

This resumes application previously paused with pause()

data_get()
delete()

Forcefully frees the given process handle.

Note that the process that the handle represents is unaffected by this function, this just stops monitoring the stdout/stderr and emitting related events.

To finish the process call terminate() or kill().

flags_get()

Retrieves the flags attached to the given process handle.

  • ECORE_EXE_PIPE_READ: Exe Pipe Read mask
  • ECORE_EXE_PIPE_WRITE: Exe Pipe Write mask
  • ECORE_EXE_PIPE_ERROR: Exe Pipe error mask
  • ECORE_EXE_PIPE_READ_LINE_BUFFERED: Reads are buffered until a newline and delivered 1 event per line.
  • ECORE_EXE_PIPE_ERROR_LINE_BUFFERED: Errors are buffered until a newline and delivered 1 event per line
  • ECORE_EXE_PIPE_AUTO: stdout and stderr are buffered automatically
  • ECORE_EXE_RESPAWN: Exe is restarted if it dies
  • ECORE_EXE_USE_SH: Use /bin/sh to run the command.
  • ECORE_EXE_NOT_LEADER Do not use setsid() to have the executed process be its own session leader
Returns:set of masks, ORed.
free()

Alias for delete() to keep compatibility with C-api.

hup()

Send hup signal (SIGHUP) to executed process.

interrupt()

Send interrupt signal (SIGINT) to executed process.

Note

Python usually installs SIGINT handler to generate KeyboardInterrupt, however Ecore will override this handler with its own that generates ECORE_EVENT_SIGNAL_EXIT in its main loop for the application to handle. Pay attention to this detail if your child process is also using Ecore.

kill()

Send kill signal (SIGKILL) to executed process.

This signal is fatal and will exit the application as it cannot be blocked.

on_add_event_add(func, *args, **kargs)

Adds event listener to know when this Exe was actually started.

The given function will be called with the following signature every time this Exe receives an ECORE_EXE_EVENT_ADD signal:

func(exe, event, *args, **kargs)

In contrast with on_exe_add_event_add(), this only receives the events from this exact exe instance. The signature is also very different, the first parameter is the Exe reference and the return value does not removes the event listener!

See:on_add_event_del()
See:on_exe_add_event_add()
on_add_event_del(func, *args, **kargs)

Removes the event listener registered with on_add_event_add().

Parameters must be exactly the same.

Raises ValueError:
 if parameters don’t match an already registered callback.
on_data_event_add(func, *args, **kargs)

Adds event listener to know when this Exe was actually started.

The given function will be called with the following signature every time this Exe receives an ECORE_EXE_EVENT_DATA signal:

func(exe, event, *args, **kargs)

In contrast with on_exe_data_event_add(), this only receives the events from this exact exe instance. The signature is also very different, the first parameter is the Exe reference and the return value does not removes the event listener!

See:on_data_event_del()
See:on_exe_data_event_add()
on_data_event_del(func, *args, **kargs)

Removes the event listener registered with on_data_event_add().

Parameters must be exactly the same.

Raises ValueError:
 if parameters don’t match an already registered callback.
on_del_event_add(func, *args, **kargs)

Adds event listener to know when this Exe was actually started.

The given function will be called with the following signature every time this Exe receives an ECORE_EXE_EVENT_DEL signal:

func(exe, event, *args, **kargs)

In contrast with on_exe_del_event_add(), this only receives the events from this exact exe instance. The signature is also very different, the first parameter is the Exe reference and the return value does not removes the event listener!

See:on_del_event_del()
See:on_exe_del_event_add()
on_del_event_del(func, *args, **kargs)

Removes the event listener registered with :py:func`on_del_event_add`.

Parameters must be exactly the same.

Raises ValueError:
 if parameters don’t match an already registered callback.
on_error_event_add(func, *args, **kargs)

Adds event listener to know when this Exe was actually started.

The given function will be called with the following signature every time this Exe receives an ECORE_EXE_EVENT_ERROR signal:

func(exe, event, *args, **kargs)

In contrast with on_exe_error_event_add(), this only receives the events from this exact exe instance. The signature is also very different, the first parameter is the Exe reference and the return value does not remove the event listener!

See:on_error_event_del()
See:on_exe_error_event_add()
on_error_event_del(func, *args, **kargs)

Removes the event listener registered with on_error_event_add().

Parameters must be exactly the same.

Raises ValueError:
 if parameters don’t match an already registered callback.
pause()

Send pause signal (SIGSTOP) to executed process.

In order to resume application execution, use continue_()

pid_get()

Retrieves the process ID of the executed process.

Return type:int
quit()

Send quit signal (SIGQUIT) to executed process.

resume()

Alias for continue_()

send(buf, size=0)

Sends data to the executed process, which it receives on stdin.

This function writes to a child processes standard in, with unlimited buffering. This call will never block. It may fail if the system runs out of memory.

Parameters:
  • buffer – object that implements buffer interface, such as strings (str).
  • size – if greater than zero, then this will limit the size of given buffer. If None, then the exact buffer size is used.
Raises ValueError:
 

if size is larger than buffer size.
Returns:

success or failure.
Return type:

bool
signal(num)

Send SIGUSR1 or SIGUSR2 to executed process.

Parm num:user signal number, either 1 or 2.
See:POSIX kill(2) and kill(1) man pages.
Raises ValueError:
 if num is not 1 or 2.
stop()

Alias for pause

tag_get()

Retrieves the tag attached to the given process.

This is a string that is attached to this handle and may serve as further information.

Note

not much useful in Python, but kept for compatibility with C-api.

Return type:str or None
tag_set(*tag)

Sets the string tag for the given process.

This is a string that is attached to this handle and may serve as further information.

Note

not much useful in Python, but kept for compatibility with C-api.

terminate()

Send terminate signal (SIGTERM) to executed process.

class efl.ecore.EventExeAdd

Bases: efl.ecore.Event

This event notifies the process created with Exe was started.

See property exe for Exe instance.

class efl.ecore.EventExeDel

Bases: efl.ecore.Event

This event notifies the process created with Exe is now dead.

See property exe for Exe instance.

class efl.ecore.EventExeData

Bases: efl.ecore.Event

This event is issued by Exe instances created with flags that allow reading from either stdout or stderr.

See properties:

  • exe instance of Exe that created this event.
  • data the raw string buffer with binary data from child process.
  • size the size of data (same as len(data))
  • lines list of strings with all text lines
© Copyright 2008-2015, Simon Busch, Gustavo Sverzut Barbieri, Ulisses Furquim, ProFUSION embedded systems, Boris Faure, Fabiano Fidencio, Davide Andreoli, Kai Huuhko.
Last updated on Aug 04, 2015. Created using Sphinx 1.3.1.