Xfce Foundation Classes
Main Page | Index | Namespace List | Alphabetical List | Class List | File List

# Xfc::G::MainContext Class Reference

A C++ interface for the GMainContext. More...

`#include <xfc/glib/main.hh>`

Inheritance diagram for Xfc::G::MainContext:

List of all members.

## Public Member Functions

Constructors

- MainContext ()
    Construct a new main context object.
- MainContext (GMainContext *context, bool owns_reference=true)
    Construct a main context from an existing GMainContext.
- virtual ~MainContext ()
    Destructor.

Accessors

- GMainContext * g_main_context () const
    Get a pointer to the GMainContext object.
- operator GMainContext * () const
    Conversion operator; Safely converts a G::MainContext object into a GMainContext pointer.
- bool pending () const
    Checks if any sources have pending events for the given context.
- GPollFunc get_poll_func () const
    Gets the poll function set by set_poll_func().

Methods

- virtual void ref ()
    Increases the reference count of the main context by one.
- virtual void unref ()
    Decreases the reference count of the main context by one.
- bool iteration (bool may_block)
    Runs a single iteration of the main loop.
- Pointer< Source > find_source (unsigned int source_id)
    Finds a Source given the source ID.
- void wakeup ()
    If the context is currently waiting in a poll(), interrupt the poll(), and continue the iteration process.
- bool acquire ()
    Tries to become the owner of the context.
- void release ()
    Releases ownership of the context previously acquired by this thread with acquire().
- bool wait (Condition &condition, Mutex &mutex)
    Tries to become the owner of the specified context, as with acquire(), but if another thread is the owner, atomically drop mutex and wait on condition until that owner releases ownership or until conditon is signaled, then try again (once) to become the owner.
- bool prepare (int *priority)
    Prepares to poll sources within a main loop.
- bool query (int max_priority, int *timeout, std::vector< PollFD > &fds)
    Determines the information necessary to poll the main loop.
- int check (int max_priority, std::vector< PollFD > &fds)
    Passes the results of polling back to the main loop.
- void dispatch ()
    Dispatches all pending sources.
- void add_poll (PollFD &fd, int priority)
    Adds a file descriptor to the set of file descriptors polled for this context.
- void remove_poll (PollFD &fd)
    Removes the file descriptor from the set of file descriptors to be polled for the context.
- void set_poll_func (GPollFunc func)
    Sets the function to use to handle the polling of file descriptors.

## Static Public Member Functions

Accessors

- Pointer< MainContext > get_default ()
    Gets the default main context.

## Detailed Description

A C++ interface for the GMainContext.

MainContext is an object representing a set of sources to be handled in a main loop. Different main contexts should be used for different threads. Single iterations of a main context can be run with iteration().

In some cases, more detailed control of exactly how the details of the main loop work is desired, for instance, when integrating the G::MainLoop with an external main loop. In such cases, you can call the component methods of iteration() directly. These methods are prepare(), query(), check() and dispatch(), and must be called in that sequence. The sequence can be stopped at any time, and you can return to prepare(), but you must never skip a step or call one of the methods twice (except for query()).

Whenever prepare() is invoked, any pending sources are cleared, and checking starts again from scratch.

## Constructor & Destructor Documentation

Xfc::G::MainContext::MainContext | ( | GMainContext * | context,
|  | bool | owns_reference = `true`
| ) | `[explicit]`

Construct a main context from an existing GMainContext.

Parameters:

  | context | A pointer to a GMainContext.
  | owns_reference | Set true if the initial reference count is owned by this object.

The MainContext object takes over the ownership of the GMainContext and unreferences it when the destructor is called.

## Member Function Documentation

bool Xfc::G::MainContext::acquire | ( |  | ) |

Tries to become the owner of the context.

Returns:
  true if the operation succeeded, and this thread is now the owner of the context.

If some other context is the owner of the context, returns false immediately. Ownership is properly recursive: the owner can require ownership again and will release ownership when release() is called as many times as acquire().

You must be the owner of a context before you can call prepare(), query(), check() and dispatch().

void Xfc::G::MainContext::add_poll | ( | PollFD & | fd,
|  | int | priority
| ) |

Adds a file descriptor to the set of file descriptors polled for this context.

Parameters:

  | fd | A PollFD object holding information about a file descriptor to watch.
  | priority | The priority for this file descriptor.

This will very seldomly be used directly. Instead a typical event source will use G::Source::add_poll() instead. The priority should be the same as the priority used for G::Source::attach() to ensure that the file descriptor is polled whenever the results may be needed.

int Xfc::G::MainContext::check | ( | int | max_priority,
|  | std::vector< PollFD > & | fds
| ) |

Passes the results of polling back to the main loop.

Parameters:

  | max_priority | The maximum numerical priority of sources to check.
  | fds | A vector of PollFD that was passed to the last call to query().

Returns:
  true if some sources are ready to be dispatched.

Pointer<Source> Xfc::G::MainContext::find_source | ( | unsigned int | source_id | ) |

Finds a Source given the source ID.

Parameters:

  | source_id | The source ID, as returned by attach() or get_id().

Returns:
  The G::Source if found, otherwise null.

Pointer<MainContext> Xfc::G::MainContext::get_default | ( |  | ) | `[static]`

Gets the default main context.

Returns:
  The default main context.

This is the main context used for main loop functions when a main context is not explicitly specified.

GPollFunc Xfc::G::MainContext::get_poll_func | ( |  | ) | const

Gets the poll function set by set_poll_func().

Returns:
  The poll function.

bool Xfc::G::MainContext::iteration | ( | bool | may_block | ) |

Runs a single iteration of the main loop.

Parameters:

  | may_block | Whether the call may block.

Returns:
  true if events were dispatched.

This involves checking to see if any event sources are ready to be processed, then if no events sources are ready and may_block is true, waiting for a source to become ready, then dispatching the highest priority events sources that are ready. Note that even when may_block is true, it is still possible for iteration() to return false, since the the wait may be interrupted for other reasons than an event source becoming ready.

bool Xfc::G::MainContext::pending | ( |  | ) | const

Checks if any sources have pending events for the given context.

Returns:
  true if events are pending.

bool Xfc::G::MainContext::prepare | ( | int * | priority | ) |

Prepares to poll sources within a main loop.

Parameters:

  | priority | The location to store the priority of the highest priority source already ready.

Returns:
  true if some source is ready to be dispatched prior to polling.

The resulting information for polling is determined by calling query().

bool Xfc::G::MainContext::query | ( | int | max_priority,
|  | int * | timeout,
|  | std::vector< PollFD > & | fds
| ) |

Determines the information necessary to poll the main loop.

Parameters:

  | max_priority | The maximum priority source to check.
  | timeout | The location to store the timeout to be used in polling.
  | fds | A vector of PollFD to store poll records that need to be polled.

Returns:
  true if any records have been stored in the vector.

void Xfc::G::MainContext::release | ( |  | ) |

| Releases ownership of the context previously acquired by this thread with acquire(). If the context was acquired multiple times, then only release ownership when release() is called as many times as it was acquired.

void Xfc::G::MainContext::remove_poll | ( | PollFD & | fd | ) |

Removes the file descriptor from the set of file descriptors to be polled for the context.

Parameters:

  | fd | A PollFD descriptor previously added with add_poll().

void Xfc::G::MainContext::set_poll_func | ( | GPollFunc | func | ) |

Sets the function to use to handle the polling of file descriptors.

Parameters:

  | func | The function to call to poll all file descriptors.

It will be used instead of the poll() system call (or GLib's replacement function, which is used where poll() isn't available). This function could possibly be used to integrate the GLib event loop with an external event loop.

virtual void Xfc::G::MainContext::unref | ( |  | ) | `[virtual]`

Decreases the reference count of the main context by one.

When the reference count becomes zero delete is called. Remember, as with all XFC Objects you must call unref() on a dynamically allocated IOChannel, not delete. If you use a smart you don't need to call unref(), the smart pointer will do that for you. You must also call unref() on an IOChannel allocated on the stack because IOChannels don't get passed on to owner objects that manage their reference count (like widgets in a container).

Reimplemented from Xfc::Trackable.

bool Xfc::G::MainContext::wait | ( | Condition & | condition,
|  | Mutex & | mutex
| ) |

Tries to become the owner of the specified context, as with acquire(), but if another thread is the owner, atomically drop mutex and wait on condition until that owner releases ownership or until conditon is signaled, then try again (once) to become the owner.

Parameters:

  | condition | A condition variable.
  | mutex | A mutex, currently held.

Returns:
  true if the operation succeeded, and this thread is now the owner of context.

The documentation for this class was generated from the following file:

- libXFCcore/xfc/glib/main.hh

Xfce Foundation Classes

Copyright © 2004-2005 The XFC Development Team | XFC 4.3