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:

Xfc::Trackable List of all members.

Public Member Functions

Constructors
Accessors
Methods

Static Public Member Functions

Accessors

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: Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC 4.3