MLib Alpha 1 API Reference

Internals

this section contains public definitions of internal MLib structures. these are mostly useful for implementers of new core classes, in order to support custom or system-specific synchronisation and thread contexts

M_Core_Class


  typedef const struct M_Core_ClassRec_*   M_Core_Class;

a pointer to a _constant_ core class. The class is used to describe the current tasking/thread sub-system to a new MLib core

M_Core_ClassRec


  typedef struct M_Core_ClassRec_
  {
    M_Core_InitFunc     core_init;
    M_Core_DoneFunc     core_done;
    
    M_ThreadID_GetFunc  thread_id_get;
    
    M_Mutex_Class       mutex_class;
    M_Synlock_Class     synlock_class;
    M_RWLock_Class      rwlock_class;    

  } M_Core_ClassRec;

a structure used to hold the MLib's interface to the platform-specific thread sub-system, if any..

fields

core_init	initialise the subsystem of a given MLib core object
core_done	finalise the subsystem of a given MLib core
thread_id_get	address of the function used to retrieve the current thread's id and its exception context.
mutex_class	pointer to system-specific mutex routines
synlock_class	pointer to system-specific synlock routines. can be NULL, in which case synlocks will be implemented as normal mutexes.
rw_lock_class	pointer to system-specific read/write lock routines. can be NULL, in which case r/w locks will be implemented as normal mutexes.

note

we do not provide thread management for now, since it's not part of our goals or requirements..

M_Core_InitFunc


  typedef M_Error      (*M_Core_InitFunc) ( M_Core     core,
                                            M_Pointer  impl_data,
                                            M_Size     xcontext_size );

a function used to initialise the implementation specific part of a given MLib core object. Usually, this is used to initialise the thread subsystem

input

mcore	handle to MLib core
impl_data	user-specified pointer. see m_core_new
xcontext_size	size in bytes of a given thread exception context

return

error code. 0 means success

note

this function should _never_ throw an exception.

M_Core_DoneFunc


  typedef void         (*M_Core_DoneFunc)  ( M_Core   core );

a function used to finalise the implementation-specific part of a given MLib core object. Usually, this is used to finalise the thread subsystem

input

mcore

handle to MLib core

M_ThreadID_GetFunc


  typedef M_ThreadID  (*M_ThreadID_GetFunc)( M_Core       core,
                                             M_Bool       create,
                                             M_XContext  *acontext );

this function is used to retrieve the current thread's ID, as well as its specific exception context when the "acontext" parameter is not NULL

input

mcore	handle to MLib core
create	when true, the function should try to create a new exception context for the current thread when it doesn't already have one. Otherwise, it should simply return NULL in "ainfo"
acontext	an optional pointer to a M_XContext handle. when this parameter is not NULL, then "*acontext" will receive the address of the thread-specific exception context.

return

current thread's id. NULL in case of failure

note

implementation-specific thread subsystems are free to use any kind of container to map thread ids to xcontexts. This ensures that the best method is always used on a given platform.

if you need to implement this function, take note that each new thread info block must be initialised with a call to ?m_thread_info_init, and finalised with ?m_thread_info_done

M_MutexRec


  typedef struct M_MutexRec_
  {
    M_Core  mcore;
    
  } M_MutexRec;

a structure that holds the public fields of a M_Mutex object

fields

mcore

handle to MLib core

M_Mutex_Class


  typedef const struct M_Mutex_ClassRec_*   M_Mutex_Class;

a handle to a constant M_Mutex_ClassRec structure used to contain the routines used to manage mutex objects

M_Mutex_ClassRec


  typedef struct M_Mutex_ClassRec_
  {
    M_Size              size;
    M_Mutex_InitFunc    init;
    M_Mutex_DoneFunc    done;
    M_Mutex_LockFunc    lock;
    M_Mutex_UnlockFunc  unlock;
  
  } M_Mutex_ClassRec;

a structure used to describe a given mutex implementation

fields

size	size of M_Mutex object in bytes. must be > sizeof( M_MutexRec )
init	mutex initializer
done	mutex finalizer
lock	mutex acquisition
unlock	mutex release

return

error code. 0 means success

note

this function should _never_ throw an exception

M_Mutex_InitFunc


  typedef  M_Error  (*M_Mutex_InitFunc)   ( M_Mutex  mutex );

a function used to initialize a new mutex object

input

mutex

target mutex handle

return

error code. 0 means success

note

this function should _never_ throw an exception

M_Mutex_DoneFunc


  typedef  void     (*M_Mutex_DoneFunc)   ( M_Mutex  mutex );

a function used to finalize a mutex object

input

mutex

target mutex handle

M_Mutex_LockFunc


  typedef  M_Error  (*M_Mutex_LockFunc)   ( M_Mutex  mutex );

a function used to lock a given mutex

input

mutex

target mutex handle

return

error code. 0 means success

note

this function should _never_ throw an exception

M_Mutex_UnlockFunc


  typedef  M_Error  (*M_Mutex_UnlockFunc) ( M_Mutex  mutex );

a function used to unlock a given mutex

input

mutex

target mutex handle

return

error code. 0 means success

note

this function should _never_ throw an exception

M_SynlockRec


  typedef struct M_SynlockRec_
  {
    M_Core  mcore;
    
  } M_SynlockRec;

a structure that holds the public fields of a M_SynlockRec object

fields

mcore

handle to MLib core

M_Synlock_Class


  typedef const struct M_Synlock_ClassRec_*   M_Synlock_Class;

a handle to a constant M_Synlock_ClassRec structure used to contain the routines used to manage synlocks

M_Synlock_ClassRec


  typedef struct M_Synlock_ClassRec_
  {
    M_Size                size;
    M_Synlock_InitFunc    init;
    M_Synlock_DoneFunc    done;
    M_Synlock_LockFunc    lock;
    M_Synlock_UnlockFunc  unlock;
    
  } M_Synlock_ClassRec;

a structure used to model a given synlock implementation

fields

size	size in bytes of synlock object. Must be > sizeof( M_SynlockRec )
init	lock initializer
done	lock finalizer
lock	lock acquisition
unlock	lock release

M_Synlock_InitFunc


  typedef M_Error      (*M_Synlock_InitFunc) ( M_Synlock  synlock );

a function used to initialise a given M_Synlock object

input

synlock

handle to new synlock. its "mcore" field is set when this function is called

return

error code. 0 means success

note

this function should never throw an exception

M_Synlock_DoneFunc


  typedef void         (*M_Synlock_DoneFunc) ( M_Synlock  synlock );

a function used to finalise a given M_Synlock object

input

synlock

handle to target synlock

note

this function is called from m_synlock_destroy . it should not free the synlock from memory..

M_Synlock_LockFunc


  typedef M_Error      (*M_Synlock_LockFunc)( M_Synlock  synlock );

a function used to lock a given synlock

input

synlock

handle to target synlock

return

error code. 0 means success

note

note that it doesn't accept a delay, for the sake of simplicity

throws

this functions must throw m_err_synlock_lock in case of failure..

M_Synlock_UnlockFunc


  typedef M_Error      (*M_Synlock_UnlockFunc) ( M_Synlock  synlock );

a function used to unlock a given synlock

input

synlock

handle to target synlock.

return

error code. 0 for success

throws

this function must throw m_err_synlock_unlock in case of failure !

M_RWLockRec


  typedef struct M_RWLockRec_
  {
    M_Core  mcore;
    
  } M_RWLockRec;

a structure that holds the public fields of a M_RWLock object

fields

mcore

handle to MLib core

M_RWLock_Class


  typedef const struct M_RWLock_ClassRec_*     M_RWLock_Class;

a handle to a constant M_RWLock_ClassRec structure used to contain the routines used to manage read/write lock objects

M_RWLock_ClassRec


  typedef struct M_RWLock_ClassRec_
  {
    M_Size                    size;
    M_RWLock_InitFunc         init;
    M_RWLock_DoneFunc         done;
    M_RWLock_ReadBeginFunc    read_begin;
    M_RWLock_ReadEndFunc      read_end;
    M_RWLock_WriteBeginFunc   write_begin;
    M_RWLock_WriteEndFunc     write_end;
    M_RWLock_UpdateBeginFunc  update_begin;
    M_RWLock_UpdateWriteFunc  update_write;
    M_RWLock_UpdateEndFunc    update_end;
  
  } M_RWLock_ClassRec;

a structure used to model a read/write lock implementation

fields

size	size of r/w lock object. must be > sizeof( M_RWLockRec )
init	lock initializer
done	lock finalizer
read_begin	lock read begin function
read_end	lock read end function
write_begin	lock write begin function
write_end	lock write end function
update_begin	lock update begin function
update_write	lock update write function
update_end	lock update end function

M_RWLock_InitFunc


  typedef M_Error    (*M_RWLock_InitFunc)       ( M_RWLock   lock );

a function used to initialize a new read/write lock

input

lock

target lock handle

return

error code. 0 means success

note

this function should _never_ throw an exception

M_RWLock_DoneFunc


  typedef void       (*M_RWLock_DoneFunc)       ( M_RWLock   lock );

a function used to finalize a given read/write lock

input

lock

target lock handle

M_RWLock_ReadBeginFunc


  typedef M_Error    (*M_RWLock_ReadBeginFunc)  ( M_RWLock  lock );

a function used to begin a read operation on a read/write lock

input

lock

target lock handle

return

error code. 0 means success

note

this function should _never_ throw an exception

M_RWLock_ReadEndFunc


  typedef M_Error    (*M_RWLock_ReadEndFunc)    ( M_RWLock  lock );

a function used to end a read operation on a read/write lock

input

lock

target lock handle

return

error code. 0 means success

note

this function should _never_ throw an exception

M_RWLock_WriteBeginFunc


  typedef M_Error    (*M_RWLock_WriteBeginFunc) ( M_RWLock  lock );

a function used to begin a write operation on a read/write lock

input

lock

target lock handle

return

error code. 0 means success

note

this function should _never_ throw an exception

M_RWLock_WriteEndFunc


  typedef M_Error    (*M_RWLock_WriteEndFunc)   ( M_RWLock  lock );

a function used to end a write operation on a read/write lock

input

lock

target lock handle

return

error code. 0 means success

note

this function should _never_ throw an exception

M_RWLock_UpdateBeginFunc


  typedef M_Error    (*M_RWLock_UpdateBeginFunc)( M_RWLock  lock );

a function used to begin an update operation on a read/write lock

input

lock

target lock handle

return

error code. 0 means success

note

this function should _never_ throw an exception

M_RWLock_UpdateWriteFunc


  typedef M_Error    (*M_RWLock_UpdateWriteFunc)( M_RWLock  lock );

a function used to write during an update operation on a read/write lock

input

lock

target lock handle

return

error code. 0 means success

note

this function should _never_ throw an exception

M_RWLock_UpdateEndFunc


  typedef M_Error    (*M_RWLock_UpdateEndFunc)  ( M_RWLock  lock );

a function used to end an update operation on a read/write lock

input

lock

target lock handle

return

error code. 0 means success

note

this function should _never_ throw an exception

generated on Tue Oct 09 23:59:46 2001