/simpletypesystem/trunk

#ifndef __H_MAIN_LOOP__

#define __H_MAIN_LOOP__

/*

Copyright (c) 2013-2016 Gustav Hartvigsson

Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the "Software"), to deal

in the Software without restriction, including without limitation the rights

to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

copies of the Software, and to permit persons to whom the Software is

furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in

all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN

THE SOFTWARE.

 */

#include "defs.h"

#include "Func.h"

#include "utils.h"

#include "utils.h"

S_BEGIN_DECLS

/**

 * @file

 * @defgroup SMainLoop SMainLoop

 * @addtogroup SMainLoop

 * @{

 * The main loop system consits of two rings. The first ring is for high

 * priority stuffs that need to be run often. The second ring is run much less

 * often than the first ring.

 *

 * The sectond ring is put in the next state only after the first ring has done

 * what is required of it.

 *

 * Please note that if you are doing pull/push of data via streams, only use one

 * or the other, do not mix ring 1 and ring 2 as that may lead to filling

 * or depleating of buffers.

 *

 * Here is an overwiev of the main loop:

 * @code

 *  Ring 1

 *   [Do event handlers] -> [IO Push] -> [IO Pull] -> [Do Workers] ->

 *       ^                                                  |

 *       |                                                  |

 *       -------------- [Sleep] <---  [Ring 2 Next] <--------

 *

 *  Ring 2

 *   [Do event handlers] -> [IO Push] -> [IO PULL]

 *         ^                                |

 *         |                                |

 *         ---------  [Do Workers] <---------

 * @endcode

 */

/* -----------------------------------------------------------------------------

 * declarations

 * -----------------------------------------------------------------------------

 */

/**

 * The structure that represents the main loop. It is seldom required to

 * directly interact with objcets of this type.

 */

typedef struct SMainLoop SMainLoop;

/**

 * The stats that the main loop can be in.

 */

typedef enum {

  S_MAIN_LOOP_STATE_NONE,

  S_MAIN_LOOP_STATE_EVENT,

  S_MAIN_LOOP_STATE_IO_PUSH,

  S_MAIN_LOOP_STATE_IO_PULL,

  S_MAIN_LOOP_STATE_DO_WORKERS,

  S_MAIN_LOOP_STATE_RING_TWO_NEXT,

  S_MAIN_LOOP_STATE_SLEEP,

  S_MAIN_LOOP_STATE_LAST

} SMainLoopState;

/**

 * The namse of the states.

 */

S_UNUSED static schar *

SMainLoopStateName [] = {

  "NONE",

  "Event",

  "Push",

  "Pull",

  "Do Work",

  "Ring Two Next",

  "Sleep",

  "NONE",

  0x0,

  0x0

};

/**

 * Get the name of the state. For use in bindings.

 */

S_EXPORTED

schar *

s_main_loop_state_get_name (SMainLoopState state);

/**

 * The different rings.

 */

typedef enum {

  S_MAIN_LOOP_RING_NONE,

  S_MAIN_LOOP_RING_ONE,

  S_MAIN_LOOP_RING_TWO,

  S_MAIN_LOOP_RING_LAST

} SMainLoopRing;

/**

 * The names of the rings

 */

S_UNUSED static schar *

SMainLoopRingName [] = {

  "NONE",

  "Ring One",

  "Ring Two",

  "NONE",

  0x0,

  0x0

};

/**

 * Get name of the ring. For used in bindings.

 */

S_EXPORTED

schar *

s_main_loop_ring_get_name (SMainLoopRing ring);

/* -----------------------------------------------------------------------------

 * definition of the real functions and stuffs.

 * -----------------------------------------------------------------------------

 */

/** @brief

 * Create a new MainLoop.

 *

 * This is something that usually is not needed, and unless you know exectly

 * what you are doing, it is never recomeded to create your own mainloops,

 * instead use @ref s_main_loop_get_default.

 */

S_EXPORTED

SMainLoop *

s_main_loop_new ();

/** @brief

 * Get the default mainloop.

 *

 * The default mainloop is the mainloop that it is recomeded to interact with.

 */

S_EXPORTED

SMainLoop *

s_main_loop_get_default ();

/** @brief

 * Run a mainloop.

 *

 * This is usually the way that applications are started, after all pre-start

 * stuffs are done.

 *

 * @param loop The mainloop to be run.

 */

S_EXPORTED

void

s_main_loop_run (SMainLoop * loop);

/** @brief

 * Quit the mainloop. This is usually the way that applications are quit.

 *

 * When this function is run, it is important that all data has been freed.

 * To assure that this has happened you can add teardown handlers to the

 * main loop using the @ref s_main_loop_add_teardown_handler function,

 * these handlers will be run when s_main_loop_quit is run.

 */

S_EXPORTED

void

s_main_loop_quit (SMainLoop * loop);

/** @brief

 * Add a reference to the main loop.

 *

 * This may or may not be useful. When the reference count reaches zero the

 * main loop will be free using @ref s_main_loop_quit.

 */

S_EXPORTED

void

s_main_loop_ref (SMainLoop * loop);

/** @brief

 * Remove a reference to the main loop.

 *

 * This may or may not be useful. When the reference count reaches zero the

 * main loop will be free using @ref s_main_loop_quit.

 */

S_EXPORTED

void

s_main_loop_unref (SMainLoop * loop);

/** @brief.

 * Add an event handler to the main loop

 *

 * @param loop The main loop to add the event hadler to.

 * @param ring To what ring to add the event handler to. (Ring 1 for high

 *             priority handlers, and ring 2 for low priority handlers.)

 * @param event_handler The event handler to be added to the main loop.

 * @param user_data The user data to be passed to the event handler. This

 *                  could be data that is relevent to the componant where the

 *                  event handler originates from.

 */

S_EXPORTED

void

s_main_loop_add_event_handler (SMainLoop * loop,

                               SMainLoopRing ring,

                               RunFunc event_handler,

                               spointer user_data);

/** @brief

 * Add an I/O push event to the main loop

 *

 * @param loop the main loop to add the I/O push event to.

 * @param ring The ring to add the I/O push event to.

 * @param push_callback The callback that prepforms the I/O push.

 * @param user_data A pointer to the data to be provided to the callback.

 */

S_EXPORTED

void

s_main_loop_add_io_push (SMainLoop * loop,

			 SMainLoopRing ring,

			 RunFunc push_callback,

			 spointer user_data);

/** @brief

 * Add a I/O pull event to the main loop.

 *

 * @param loop The loop to add the I/O pull event to.

 * @param ring The ring to add the evet to.

 * @param pull_callback The callback to be performs the I/O pull.

 * @param user_data The data to be provided to the callback.

 */

S_EXPORTED

void

s_main_loop_add_io_pull (SMainLoop * loop,

			 SMainLoopRing ring,

			 RunFunc pull_callback,

			 spointer user_data);

/** @brief

 * Add a worker to the main loop.

 *

 * @param loop The loop to add the worker to.

 * @param ring The ring to add the worker to.

 * @param pull_callback The worker callback.

 * @param user_data The data to be provided to the callback.

 */

S_EXPORTED

void

s_main_loop_add_worker (SMainLoop * loop,

			SMainLoopRing ring,

			RunFunc worker_callback,

			spointer user_data);

/** @brief

 * Add a teardown handler.

 *

 * A teardown handler is a function that

 *

 * @param loop The loop to add the teardown handler to.

 * @param teardown_handler The teardown handler.

 * @param self The self object that is to be torn down.

 * @param user_data A pointer to be provided to the callback.

 */

S_EXPORTED

void

s_main_loop_add_teardown_handler (SMainLoop * loop,

				  Callback teardown_handler,

				  spointer self,

				  spointer user_data);

/**

 * @section THREAD_SAFTEY THREAD SAFTEY

 */

S_EXPORTED

inline void FOOL_DOXYGEN ();

/** @brief

 * lock the main loop form tampering from other threads.

 *

 * This function locks the main loop's mutex so that no changes can

 * be done to the loop whilst it is locked.

 *

 * @param loop The main loop to be locked.

 */

S_EXPORTED

void

s_main_loop_lock (SMainLoop * loop);

/** @brief

 * lock the main loop form tampering from other threads.

 *

 * This function locks the main loop's mutex so that no changes can

 * be done to the loop whilst it is locked.

 *

 * @param loop The loop to be unlocked.

 */

S_EXPORTED

void

s_main_loop_unlock (SMainLoop * loop);

/**

 * @}

 */

S_END_DECLS

#endif /* __H_MAIN_LOOP__ */