exec : Index | Toc |
Background | |
TGetExecBase | Get Execbase pointer from an Exec object |
Overview | |
Memory | Memory managers, allocation and manipulation |
Modules | Module opening, closing and instances |
Tasks | Tasks, signals and waiting |
Locking | Locks and named atoms |
Ports | Ports, messages and I/O requests |
Internal | Exec-internal functions |
exec : Memory | Toc |
Standard allocation | |
TAlloc | Allocate from memory manager |
TFree | Return memory to memory manager |
TRealloc | Resize an allocation made from a memory manager |
TGetSize | Get size of an allocation |
TGetMMU | Get MMU to which an allocation belongs |
TAllocMsg | Allocate memory for a message |
Memory managers | |
TCreateMMU | Create a memory manager |
TGetTaskMMU | Get a task's inbuilt memory manager |
TCreatePool | Create a memory pool |
TAllocPool | Allocate from a pool |
TReallocPool | Resize a pool allocation |
TFreePool | Free pool allocation |
Memory manipulation | |
TCopyMem | Copy memory |
TFillMem | Fill memory |
TFillMem32 | Fill memory with a 32bit value |
exec : Modules | Toc |
Modules | |
TOpenModule | Open a shared module (or instance) |
TCloseModule | Close a module (or instance) |
exec : Tasks | Toc |
Tasks | |
TCreateTask | Create a task at a function |
TFindTask | Find a named task |
TSetTaskData | Set task's user data packet |
TGetTaskData | Get task's user data packet |
TGetUserPort | Get a task's inbuilt message port |
TGetSyncPort | Get a task's inbuilt sync/reply port |
TGetTaskMMU | Get a task's inbuilt memory manager |
Signals | |
TAllocSignal | Allocate user signal |
TFreeSignal | Release user signal |
TSignal | Send signal to a task |
TSetSignal | Get/set task's signal state |
TWait | Suspend task to wait for a signal |
TGetPortSignal | Get a message port's signal |
exec : Locking | Toc |
Locks | |
TCreateLock | Create locking object |
TLock | Lock |
TUnlock | Unlock |
Atoms | |
TLockAtom | Create/obtain a named atom |
TUnlockAtom | Release/destroy a named atom |
TSetAtomData | Attach data packet to a named atom |
TGetAtomData | Get data packet from a named atom |
exec : Ports | Toc |
Ports | |
TCreatePort | Create a message port |
TWaitPort | Wait for a port to become non-empty |
TGetUserPort | Get a task's inbuilt message port |
TGetSyncPort | Get a task's inbuilt sync/reply port |
TGetPortSignal | Get a message port's signal |
Messages | |
TAllocMsg | Allocate memory for a message |
TPutMsg | Put a message to a port, asynchronously |
TGetMsg | Get message from a port |
TAckMsg | Acknowledge message to sender |
TReplyMsg | Reply message to sender |
TDropMsg | Abandon message, make it fail at sender |
TSendMsg | Send a message, synchronously |
I/O requests | |
TDoIO | Do an I/O request synchronously |
TPutIO | Send an I/O request asynchronously |
TWaitIO | Wait for completion of an I/O request |
TAbortIO | Try to abort an I/O request |
TCheckIO | Check for completion of an I/O request |
exec : Internal | Toc |
Internal | |
TGetHALBase | Get HAL module base pointer |
TDoExec | Run the Execbase context |
TCreateSysTask | Create an Exec-internal task |
exec : TGetExecBase | Toc |
TGetExecBase - Get Exec module base pointer
TExecBase = TGetExecBase(object) TAPTR TAPTR
object Pointer to an Exec object
TExecBase Pointer to Exec module base
The TEKlib framework is free of global data and carefully designed to be fully reentrant. It is the programmer's choice to put module base pointers into global variables.Initially, an application is entered with a task handle only. It is usually required to query the Exec base pointer from that handle before anything useful can be done. The module base pointer can then be stored in a global variable, if desired.A typical application startup may look like this:TAPTR TExecBase; TAPTR TUtilBase; TTASKENTRY TVOID TEKMain(TAPTR entrytask) { TExecBase = TGetExecBase(entrytask); TUtilBase = TOpenModule("util", ... ... }
exec : TGetHALBase | Toc |
TGetHALBase - Get HAL module base pointer
THALBase = TExecGetHALBase(TExecBase) TAPTR TAPTR THALBase = TGetHALBase() TAPTR
Return a pointer to the HAL module. Access to the HAL layer can be required in device driver implementations. It is normally not needed in regular applications.
THALBase HAL module base pointer
exec : TCreateSysTask | Toc |
TCreateSysTask - create system internal task
task = TExecCreateSysTask(TExecBase, func, tags) TAPTR TAPTR TTASKFUNC TTAGITEM* task = TCreateSysTask(func, tags) TAPTR TTASKFUNC TTAGITEM*
Create an Exec-internal task. If func is TNULL then a TEKlib task is placed into the caller's context, otherwise a new thread of execution is started at the given function.This function is used to setup an initial TEKlib context (or an Exec task) before TEKlib is fully initialized. This function is not entirely safe in regular applications and the only sanctioned use is in startup libraries.Applications use TCreateTask.
func Pointer to function, or TNULL for current context tags Pointer to an array of tag items
TTask_Name, (TSTRPTR)Pointer to a string for the task name. default: TNULLTTask_UserData, (TAPTR)Pointer to an initial user data packet. default: TNULL
task Task handle, or TNULL if initialization failed
exec : TOpenModule | Toc |
TOpenModule - Open a module
modbase = TExecOpenModule(TExecBase, name, version, tags) TAPTR TAPTR TSTRPTR TUINT16 TTAGITEM* modbase = TOpenModule(name, version, tags) TAPTR TSTRPTR TUINT16 TTAGITEM*
Open a module or a module instance. When the module's version is greater or equal the requested version and when the module can be loaded and initialized successfully then a pointer to the module base (or to a module instance) will be returned to the caller.
name Name of the module version Minimal module version for the open to succeed tags Pointer to an array of tag items
Tags passed to TOpenModule can be intercepted in the module open function and be used like a variable list of arguments to a constructor. There are currently no tags defined for TOpenModule itself. See the module writing tutorial for further details.
modbase Module base or TNULL Returns TNULL if the module could not be found, when it failed to initialize or when it was in memory already, but the version requirement could not be satisfied.
Each successful open to a module must be paired with exactly one matching call to TCloseModule, or TEKlib will panic (raise a fatal exception, "crash"...) at exit.
exec : TCloseModule | Toc |
TCloseModule - Close a module
TExecCloseModule(TExecBase, modbase) TAPTR TAPTR TCloseModule(modbase) TAPTR
Close a module or module instance. When applied to the last reference or instance open then the module will be deinitalized, unloaded and freed.
module Module or module instance. It is safe to pass TNULL.
exec : TCopyMem | Toc |
TCopyMem - Copy a block of memory
TExecCopyMem(TExecBase, source, dest, numbytes) TAPTR TAPTR TAPTR TUINT TCopyMem(source, dest, numbytes) TAPTR TAPTR TUINT
Copy the given number of bytes from a source to destination address in memory.
source Source address dest Destination address numbytes Number of bytes to copy
- You cannot rely on overlapping copies to work with this function.
exec : TFillMem | Toc |
TFillMem - Fill a block of memory
TExecFillMem(TExecBase, start, numbytes, fillval) TAPTR TAPTR TUINT TUINT8 TFillMem(start, numbytes, fillval) TAPTR TUINT TUINT8
Fill a range of memory with a byte value.
start Start address numbytes Number of bytes to fill fillval byte value
exec : TFillMem32 | Toc |
TFillMem32 - Fill a block of memory, 32bit aligned
TExecFillMem32(TExecBase, start, numbytes, fillval) TAPTR TAPTR TUINT TUINT TFillMem32(start, numbytes, fillval) TAPTR TUINT TUINT
Fill a range of memory with a 32 bit value. The start address must be 32bit aligned and numbytes must be evenly divisable by four.
start Start address numbytes Number of bytes to fill fillval 32 bit value
exec : TCreateMMU | Toc |
TCreateMMU - Create a memory manager
mmu = TExecCreateMMU(TExecBase, allocator, type, tags) TAPTR TAPTR TAPTR TUINT TTAGITEM* mmu = TCreateMMU(allocator, type, tags) TAPTR TAPTR TUINT TTAGITEM*
Create a memory manager, also known as a MMU. A memory manager can be passed to TAlloc for allocations with features such as leak tracking, automatic cleanup, cross-task protection etc.The purpose of memory managers is to hook special capabilities into a particular domain of code, when it is suspected to leak memory for example. Memory managers can be stacked on top of each other.TNULL is always a valid memory manager. A TNULL MMU will cause TAlloc to direct requests to the general purpose allocator.Only a TNULL MMU is intrinsically safe to use in a multitasking environment. Other allocators must implement cross-task protection explicitely. See the TMMUT_TaskSafe flag for details.A MMU is destroyed with a call to teklib:TDestroy.
allocator Parent MMU, underlying allocator or TNULL type Type of MMU to be created tags Pointer to an array of tag items Types:TMMUT_MMUSetup a MMU on top of another MMU, implementing no additional functionality. Allocator must be TNULL or point to another MMU. An underlying TNULL MMU results in a memory manager that is equivalent to a TNULL MMU.TMMUT_TaskSafeSetup a MMU on top of another MMU, implementing safe accesses across tasks, that is, multiple tasks are allowed to operate on the resulting MMU in parallel. Allocator must be TNULL or point to another MMU.TMMUT_TrackingSetup a tracking MMU on top of another MMU. Allocator must be TNULL or point to another MMU. The resulting MMU will return all pending allocations to its parent when it is being destroyed, at the cost of extra performance and memory consumption. This type can be combined with TMMUT_TaskSafe.TMMUT_StaticThe resulting MMU will manage a static block of memory. When the block is exhausted or fragmented then further allocations will fail, as no attempts are made to get more storage from the outside. Allocator is expected to be a pointer to a block of memory or TNULL. The tag TMem_StaticSize must be specified in the taglist (see below). This type can be combined with TMMUT_TaskSafe.TMMUT_PooledThe resulting MMU will group small allocations into larger ones. All pending allocations will be freed when the MMU is being destroyed. Allocator must be a pointer to a pool created with TCreatePool or TNULL. In the latter case a pooled allocator will be created and maintained internally with the resulting MMU, and pool-specific tags passed to TCreateMMU will be used accordingly. See TCreatePool for details. This type can be combined with TMMUT_TaskSafe.TMMUT_VoidThe resulting MMU will be incapable of allocating memory. Attempts to do so will always return a TNULL pointer. This type can be useful for debugging purposes.
TMem_StaticSize, (TUINT)This argument is mandatory when type is TMMUT_Static. It specifies the size of a static block of memory to be managed. Allocator is expected to be a pointer to a block of memory of the specified size, or TNULL. In the latter case a block of this size will be allocated and maintained internally and freed when the resulting MMU is being destroyed. Default: 0TMem_LowFrag, (TBOOL)This tag is considered when type is TMMUT_Static and it will cause the resulting MMU to use an allocation strategy that may help to reduce internal fragmentation at the cost of extra performance. This is also known as the 'best match' strategy. The default is the 'first match' strategy. Default: TFALSE
mmu Memory manager, or TNULL if initialization failed.
- Tracking MMUs return all memory to their parent when they are being destroyed. The number of pending allocations will be reported to stderr (or to a platform-specific debug channel) when a debug build of the Exec module is used.
exec : TAlloc | Toc |
TAlloc - Allocate memory
mem = TExecAlloc(TExecBase, mmu, size) TAPTR TAPTR TAPTR TUINT mem = TAlloc(mmu, size) TAPTR TAPTR TUINT
This function allocates a block of memory from a memory manager. A pointer to the allocated block of memory is returned, or TNULL when the request cannot be satisfied.A TNULL memory manager is valid and directs requests to the system's general purpose allocator.
mmu Pointer to a memory manager, or TNULL size Size of the allocation [bytes]
mem Pointer to a block of memory, or TNULL if out of memory
exec : TAlloc0 | Toc |
TAlloc0 - Allocate from a memory manager, blank
mem = TExecAlloc0(TExecBase, mmu, size) TAPTR TAPTR TAPTR TUINT mem = TAlloc0(mmu, size) TAPTR TAPTR TUINT
Allocate a blank block of memory from a memory manager. This function is equivalent to TAlloc except for that the returned memory is guaranteed to be filled with all bytes set to zero.
mmu Pointer to a memory manager or TNULL size Size of the allocation [bytes]
mem Pointer to a block of memory, or TNULL if out of memory
exec : TAllocMsg | Toc |
TAllocMsg - Allocate memory for a message
msg = TExecAllocMsg(TExecBase, size) TAPTR TAPTR TUINT msg = TAllocMsg(size) TAPTR TUINT
size Size of the requested block of memory [bytes]
msg Pointer to message memory, or TNULL if failed
- Messages cannot be reallocated. The result from attempts to do so will always return TNULL.
- Never rely on allocations made with this function to be filled with all bytes set to zero. Use TAllocMsg0 to get a blank allocation.
exec : TAllocMsg0 | Toc |
TAllocMsg0 - Allocate memory for a message, blank
msg = TExecAllocMsg0(TExecBase, size) TAPTR TAPTR TUINT msg = TAllocMsg0(size) TAPTR TUINT
Allocate memory for a message, blank. This function is equivalent to TAllocMsg, except for that the returned memory is guaranteed to be filled with all bytes set to zero.
size Size of the requested block of memory [bytes]
mem Pointer to message memory, or TNULL if failed
exec : TFree | Toc |
TFree - Return memory to its memory manager
TExecFree(TExecBase, mem) TAPTR TAPTR TFree(mem) TAPTR
Return a block of memory to the memory manager from which it has been allocated.
mem Block of memory to be freed. It is safe to pass TNULL.
- This function is responsible for freeing memory that has been allocated using TAlloc and TAllocMsg. It cannot be used for freeing memory that has been allocated with TAllocPool. For the latter see TFreePool.
exec : TRealloc | Toc |
TRealloc - Resize an allocation
newmem = TRealloc(oldmem, newsize) TAPTR TAPTR TUINT
Resize a block of memory that has been allocated from a memory manager. If newsize is zero then the allocation will be freed and the result will be TNULL.This function departs from the standard realloc semantics; When a TNULL pointer is passed in the oldmem argument then this function will always return TNULL; it cannot be used to allocate a fresh block of memory.If a reallocation fails and the return value is TNULL then the old block is still allocated.
oldmem Pointer to memory allocated newsize New size for the allocation or 0
newmem Pointer to memory reallocated to newsize, or TNULL
- Reallocation may require that the given block of memory needs to be moved in memory, that is, pointers to this area may become invalid. Consider this.
- This function is responsible for resizig allocations that have been made using TAlloc. It cannot be used for allocations made from pools. For the latter, see TReallocPool.
exec : TGetSize | Toc |
TGetSize - Get size of an allocation
size = TExecGetSize(TExecBase, mem) TUINT TAPTR TAPTR size = TGetSize(mem) TUINT TAPTR
Get the size of a block of memory in bytes that has been allocated from a memory manager.
mem Pointer to a block of memory
size size of the allocation [bytes]
exec : TGetMMU | Toc |
TGetMMU - Get an allocation's memory manager
mmu = TExecGetMMU(TExecBase, mem) TAPTR TAPTR TAPTR mmu = TGetMMU(mem) TAPTR TAPTR
Return a pointer to the memory manager an allocation was made from.
mem Pointer to a block of memory
mmu Pointer to a memory manager
- TNULL is a valid memory manager, referring to the system's general-purpose allocator.
exec : TCreateLock | Toc |
TCreateLock - Create a lock
lock = TExecCreateLock(TExecBase, tags) TAPTR TAPTR TTAGITEM* lock = TCreateLock(tags) TAPTR TTAGITEM*
Create a locking object. A lock is a mechanism to protect resources from simultaneous accesses from multiple tasks. Only one accessor can hold the same lock at a given time.A lock is destroyed with a call to teklib:TDestroy.
tags Pointer to an array of tag items
None defined yet.
lock Lock created, or TNULL if creation failed
exec : TLock | Toc |
TLock - Gain exclusive access to a lock
TExecLock(TExecBase, lock) TAPTR TAPTR TLock(lock) TAPTR
Gain exclusive access to a lock. If another task is currenty holding the lock then the caller will block until the lock is free. If no other task holds the lock then this function returns immediately with exclusive access.This function is recursive (or 'nesting'), i.e. it may be called subsequently when the lock is already held by the current owner. In that case an internal counter is increased and this function returns immediately.Each call per task must be paired with exactly one matching call to TUnlock, which will decrease the counter. When the counter reaches zero then the control is handed over to the next waiter, or in case there are no waiters the lock is being released.
lock Pointer to a lock created with TCreateLock
exec : TUnlock | Toc |
TUnlock - Release access to a lock
TExecUnlock(TExecBase, lock) TAPTR TAPTR TUnlock(lock) TAPTR
Release access to a lock which was previously obtained with a call to TLock. The next task currently suspended waiting for the lock will gain exclusive access to the resource and resume.
lock Pointer to a locking object in locked state
exec : TAllocSignal | Toc |
TAllocSignal - Allocate a single or a set of signals
signals = TExecAllocSignal(TExecBase, prefsignals) TUINT TAPTR TUINT signals = TAllocSignal(prefsignals) TUINT TUINT
Allocate a signal (or a set of preferred signals) from the current task. If prefsignals is 0 then this function will try to reserve any single free signal. Otherwise this function tries to reserve the exact set specified and returns 0 if any of the specified signals are already in use.
prefsignals Preferred set of signals or 0 for any free signal
signals Signals allocated Zero if out of signals, or when any of the signal bits in prefsignals are already in use.
- Signals no longer needed should be freed using TFreeSignal.
- In the current implementation of the Exec module, up to 28 signals per task can be allocated by the user. It is guaranteed that there will be always at least 20 signals per task available for the user.
exec : TFreeSignal | Toc |
TFreeSignal - Free signals
TExecFreeSignal(TExecBase, signals) TAPTR TUINT TFreeSignal(signals) TUINT
Free a single or a set of signals and return them to a task's signal pool.
signals Signal mask to be freed. It is safe to pass 0.
exec : TSignal | Toc |
TSignal - Submit signals to a task
TExecSignal(TExecBase, task, signals) TAPTR TAPTR TUINT TSignal(task, signals) TAPTR TUINT
Submit signals to a task. The signal(s) will show up in the signalled task. When the task was suspended waiting for any of the specified signals then it will resume its operation.
task Task to be signalled signals A set of signals to be submitted
exec : TSetSignal | Toc |
TSetSignal - Set and get task's signal state
oldsignals = TExecSetSignal(TExecBase, newsignals, sigmask) TUINT TAPTR TUINT TUINT oldsignals = TSetSignal(newsignals, sigmask) TUINT TUINT TUINT
Set the current task's signal state to the signal bits in newsignals, masked through the bits in the sigmask argument, and return the old state of the tasks's signals.
newsignals New set of signals sigmask Signal bits to be affected
/* get the current state of all signals, but do not modify them */ signals = TSetSignal(0, 0); /* clear the TTASK_SIG_ABORT signal */ TSetSignal(0, TTASK_SIG_ABORT);
exec : TWait | Toc |
TWait - Wait for signals
signals = TExecWait(TExecBase, sigmask) TUINT TAPTR TUINT signals = TWait(sigmask) TUINT TUINT
Suspend the current task to wait for one or more of the specified signals to arrive. Those bits will be cleared from the task's signal state and returned to the caller when the function returns. If sigmask is 0 then this function will immediately return 0.
sigmask Set of signals to wait for
signals Signals that caused returning
- For waiting with timeout see time:TWaitTime.
exec : TCreatePort | Toc |
TCreatePort - Create a message port
port = TExecCreatePort(TExecBase, tags) TAPTR TAPTR TTAGITEM* port = TCreatePort(tags) TAPTR TTAGITEM*
Create a message port owned by the current task.A message port is an access point for messages between tasks. It can be synchronized on using TWaitPort. Use TGetPortSignal to retrieve a port's underlying signal bit. Using this signal one or more message ports can be synchronized on using TWait.A message port is destroyed with a call to teklib:TDestroy.
tags Pointer to an array of tag items
None defined yet
port Message port created, or TNULL for failure
- Every task has an inbuilt user message port already. See TGetUserPort for details. Use TCreatePort to create more ports if necessary.
exec : TWaitPort | Toc |
TWaitPort - Wait for a message port to become non-empty
msg = TExecWaitPort(TExecBase, port) TAPTR TAPTR TAPTR msg = TWaitPort(port) TAPTR TAPTR
Suspend the current task to wait for a message to arrive at the given message port. When a message is already present then this function returns immediately. A pointer to the next pending message is returned to the caller, but it is not removed from the queue. Use TGetMsg to unlink the next message from a port.
port Message port
msg Next pending message in the queue
- The port must have been created in and be owned by the caller's task context.
- Message ports in local address space have no timeout. If no message arrives at the specified port then this function will wait and block eternally.
- Use TGetUserPort to combine the signals from multiple message ports and synchronize on them using TWait.
exec : TAckMsg | Toc |
TAckMsg - Acknowledge message to its sender
TExecAckMsg(TExecBase, msg) TAPTR TAPTR TAckMsg(msg) TAPTR
Acknowledge a two-way message to its sender, i.e. return it to the replyport that was specified by the sender when the message was sent.It is safe to apply this function to one-way messages as well; if the message was sent without a reply or acknowledgement expected then it will be silently returned to its memory manager.When a message is returned with this function then the sender must not rely on modifications made inside the message body. If you send a message back after you changed its contents then TReplyMsg should be used instead.
msg Message to be acknowledged or to be freed, transparently
exec : TReplyMsg | Toc |
TReplyMsg - Reply message to its sender
TExecReplyMsg(TExecBase, msg) TAPTR TAPTR TReplyMsg(msg) TAPTR
Reply a two-way message to its sender, i.e. return it to the replyport that was specified by the sender when the message was sent.It is safe to apply this function to one-way messages as well; if the message was sent without a reply or acknowledgement expected then this function will silently return the message to the memory manager it was allocated from.Use this function for transferring a modified message body back to its sender. If the message was not modified and it is only required to inform the sender that it has been processed then TAckMsg should be preferred.
msg Message to be replied (or to be freed, transparently)
exec : TDropMsg | Toc |
TDropMsg - Abandon a message
TExecDropMsg(TExecBase, msg) TAPTR TAPTR TDropMsg(msg) TAPTR
Abandon a two-way message, i.e. return it to its replyport with the internal message status set to TMSG_STATUS_FAILED. This function is not guaranteed to return any modifications made inside the message body, it will only indicate failure.It is safe to apply this function to one-way messages as well; if the message was sent without a reply or acknowledgement expected then it will be silently returned to its memory manager.In local address space this function is particularly useful for indicating failure to a synchronized message sent with TSendMsg.
msg Message to be abandoned (or to be freed, transparently)
exec : TPutMsg | Toc |
TPutMsg - Send a message asynchronously
TExecPutMsg(TExecBase, port, replyport, msg) TAPTR TAPTR TAPTR TAPTR TPutMsg(port, replyport, msg) TAPTR TAPTR TAPTR
Put a message to a message port. If a replyport is specified then the message will be sent two-way and there will be a reply expected at the replyport. If replyport is TNULL then the message will be sent one-way and does not return to the sender.
port Addressed message port replyport Replyport or TNULL if no reply is expected msg Message to be sent
exec : TGetMsg | Toc |
TGetMsg - Get message
msg = TExecGetMsg(TExecBase, port) TAPTR TAPTR TAPTR msg = TGetMsg(port) TAPTR TAPTR
Unlink the next pending message from a port's message queue and return it to the caller. This function does not block; if the message queue is empty then this function returns immediately with TNULL.
port Message port to get next message from
msg Next pending message or TNULL if the queue was empty
exec : TSendMsg | Toc |
TSendMsg - Send a message, synchronized
status = TExecSendMsg(TExecBase, port, msg) TUINT TAPTR TAPTR TAPTR status = TSendMsg(port, msg) TUINT TAPTR TAPTR
This function sends a message two-way, synchronized, waiting for a reply or an acknowledgement before it returns to the caller.The return value will be set to zero (TMSG_STATUS_FAILED) if the message has been dropped, or, depending on the return method, TMSG_STATUS_REPLIED or TMSG_STATUS_ACKD if it returned successfully.
port Message port to send message to msg Message to be sent
status delivery status of the message TMSG_STATUS_FAILED if the message was dropped TMSG_STATUS_REPLIED if replied TMSG_STATUS_ACKD if acknowledged
Message ports in local address space have no timeout. If the message is not being dropped, replied or acknowledged then this function blocks eternally.
exec : TGetPortSignal | Toc |
TGetPortSignal - Get a message port's signal
signal = TExecGetPortSignal(TExecBase, port) TUINT TAPTR TAPTR signal = TGetPortSignal(port) TUINT TAPTR
This function retrieves a message port's underlying signal. The typical use of that signal is to use TWait to combine waiting for messages from multiple ports.
port Message port to get signal from
signal The signal that shows up in the port's task
exec : TGetUserPort | Toc |
TGetUserPort - get a task's userport
userport = TExecGetUserPort(TExecBase, task) TAPTR TAPTR TAPTR userport = TGetUserPort(task) TAPTR TAPTR
Get a pointer to a task's primary, asynchronous message port which is reserved for the user. If the task argument is TNULL then the caller's own task will be queried.Each task is supplied with an user port upon creation. More message ports can be created using TCreatePort during a task's lifetime.
task Task handle, or TNULL
userport Pointer to task's userport
- The user port's underlying signal bit is TTASK_SIG_USER.
exec : TGetSyncPort | Toc |
TGetSyncPort - Get a task's syncport
syncport = TExecGetSyncPort(TExecBase, task) TAPTR TAPTR TAPTR syncport = TGetSyncPort(task) TAPTR TAPTR
Get a pointer to a task's inbuilt syncport. If task is TNULL then the caller's own task will be addressed.The syncport is reserved for synchronized message replies; It can be employed by the user if its usage remains strictly limited to that purpose.For instance, it is not allowed to send messages using TPutMsg expecting a reply at a syncport. This would break Exec functions that might use the syncport or the syncport's signal internally. For asynchronous message communication use the task's userport, or create a new port using TCreatePort.
task Task handle, or TNULL
syncport Pointer to task's syncport
exec : TCreateTask | Toc |
TCreateTask - Create task
task = TExecCreateTask(TExecBase, function, initfunc, taglist) TAPTR TAPTR TTASKFUNC TINITFUNC TTAGITEM* task = TCreateTask(function, initfunc, taglist) TAPTR TTASKFUNC TINITFUNC TTAGITEM*
Create a task and launch a new thread of execution at the specified function.The initfunc argument is optional and can be used for calling a function in the child context that will be in synchronization with the caller. The main function will be entered only if initfunc returns TTRUE, otherwise task creation will be abandoned and TCreateTask returns TNULL.A task handle is destroyed with a call to teklib:TDestroy. This will synchronize on the task's completion and free its resources. TEKlib tasks must always leave gently through their function exit and all task must be synchronized on properly, or the TEKlib framework may panic (raise a fatal exception, "crash"...) at exit.
function Main function to call in child context. May be TNULL. initfunc Init function in child context. May be TNULL. taglist Pointer to an array of tag items.
TTask_UserData, TAPTRPointer to a initial user data pointer that will be supplied to the newly created task. It can be queried from the task handle using TGetTaskData. Default: TNULLTTask_Name, TSTRPTRPointer to the task's name. If supplied then the task can be found system-wide using TFindTask. Default: TNULLTTask_CurrentDir, TAPTRWith this argument you can specify a directory lock that will be duplicated and used as the new task's current directory. By default, tasks inherit their current directory from their parent. Default: Caller's current directoryTTask_InputFH, (TAPTR), TTask_OutputFH, (TAPTR), TTask_ErrorFH, (TAPTR),These tags allow the caller to pass filehandles to the newly created task for standard input, ouput and error, respectively. By default, the I/O handles for newly created tasks are unset and opened on demand, that is, by the I/O module in an attempt to open the devices "stdio:in", "stdio:out" or "stdio:err", respectively.
task Task, or TNULL if the task could not be established
exec : TFindTask | Toc |
TFindTask - Find a task
task = TExecFindTask(TExecBase, name) TAPTR TAPTR TSTRPTR task = TFindTask(name) TAPTR TSTRPTR
Find a named task in the system. If name is TNULL then this function will return a pointer to the caller's own task.
name Name of a task or TNULL for finding the caller's own task
task Pointer to a task handle or TNULL if not found
exec : TGetTaskData | Toc |
TGetTaskData - Get task userdata
userdata = TExecGetTaskData(TExecBase, task) TAPTR TAPTR TAPTR userdata = TGetTaskData(task) TAPTR TAPTR
Get a pointer to a task's userdata. A userdata pointer can be supplied upon task creation using the TTask_UserData tag, and set with TSetTaskData during a task's lifetime.
task Task handle or TNULL to query the caller's own task
userdata Pointer to a task's userdata
exec : TSetTaskData | Toc |
TSetTaskData - Set task userdata
olddata = TExecSetTaskData(TExecBase, task, userdata) TAPTR TAPTR TAPTR TAPTR olddata = TSetTaskData(task, userdata) TAPTR TAPTR TAPTR
Set a task's userdata pointer and return the previous userdata pointer to the caller.A userdata pointer can be supplied upon task creation using the TTask_UserData tag and queried with TGetTaskData during a task's lifetime.
task Task handle or TNULL to address the caller's own task userdata New data to associate with the task
olddata Pointer to task's previous userdata
exec : TGetTaskMMU | Toc |
TGetTaskMMU - Get a task's memory manager
mmu = TExecGetTaskMMU(TExecBase, task) TAPTR TAPTR TAPTR mmu = TGetTaskMMU(task) TAPTR TAPTR
Get a pointer to a task's inbuilt memory manager. Allocations made from this memory manager are automatically freed when the task exits.
task Task handle, or TNULL to query the caller's own task
mmu Task's memory manager
exec : TLockAtom | Toc |
TLockAtom - Create, obtain, destroy an atom
atom = TExecLockAtom(TExecBase, data, mode) TAPTR TAPTR TATPR TUINT atom = TLockAtom(data, mode) TAPTR TATPR TUINT
Depending on the mode argument this function creates, obtains or destroys a named atom. Atoms are an extension to locks, allowing multiple lockers to create, locate and access resources by name. In addition to locks atoms allow shared locking and locking attempts.Atoms are recursive. This means the same task holding a lock on an atom is allowed to claim it subsequently, and this function immediately returns with a nesting lock. All locks per task must be paired with exactly one matching unlock operation.Once locked by the caller, a data field can be associcated with an atom using TSetAtomData and retrieved with TGetAtomData.The mode argument determines the kind of action to be taken:TATOMF_NAMEThis flag indicates that the data argument is expected to be a pointer to a name. Otherwise it's expected to be a pointer to an existing atom.TATOMF_KEEPIf data is a pointer to a name and if no atom of that name existed, TNULL is returned. Otherwise this function returns with a lock on the atom. Atom is returned.TATOMF_CREATEIf combined with TATOMF_NAME and when an atom of that name did not exist, it is created and returned in locked state. Returns TNULL if out of memory.TATOMF_DESTROYIf the atom exists then it is locked and destroyed. If the atom does not exist or if the mode is combined with TATOMF_TRY and the atom is in use elsewhere, TNULL is returned. Otherwise a non-TNULL value is returned.TATOMF_TRYIf the atom is currently locked exclusively then returns immediately with TNULL. If the atom is currently locked shared then attempts to lock it exclusively return immediately with TNULL. Also returns TNULL if combined with TATOMF_CREATE and TATOMF_NAME and when an atom of that name already exists.TATOMF_SHAREDLock in shared mode. Multiple tasks claiming a shared lock at the same time can succeed. If an atom is currently held exclusively then all shared lockers will block until the exclusive lock is released. If an atom is locked in shared mode then attempts to lock it exclusively will block until the atom is free.By special convention, TATOMF_CREATE|TATOMF_SHARED returns with a shared lock only if an atom of that name already existed. When an atom of that name did not exist then it is created and returned in exclusively locked state; this allows to safely associate an initial data packet to an atom that is used in shared mode later on.
data Pointer to an existing atom, or to a name mode Access flags, see above
atom Pointer to an atom in locked state, or TNULL if failed
- If the caller holds an exclusive lock on an atom then it is possible to request a subsequent shared lock. The result will be another nesting lock on the atom.
- If the caller holds a shared lock on the atom then it is not allowed to request a subsequent exclusive lock. The results will be undefined.
- Not all possible combinations of the mode flags make sense; TATOMF_CREATE without TATOMF_NAME will currently return TNULL. The combination of TATOMF_CREATE and TATOMF_DESTROY is undefined.
- Prior to Exec v3, TATOMF_DESTROY always returned TNULL and the combination with TATOMF_TRY was not documented.
exec : TUnlockAtom | Toc |
TUnlockAtom - Release access to an atom
TExecUnlockAtom(TExecBase, atom, mode) TAPTR TAPTR TUINT TUnlockAtom(atom, mode) TAPTR TUINT
Release access to an atom that has been locked with TLockAtom. Modes:
TATOMF_KEEP Release only TATOMF_DESTROY Release and destroy the atom
atom Atom previously locked mode Unlocking mode, see above
exec : TSetAtomData | Toc |
TSetAtomData - Set an atom's data tag
olddata = TExecSetAtomData(TExecBase, atom, data) TTAG TAPTR TAPTR TTAG olddata = TSetAtomData(atom, data) TTAG TAPTR TTAG
Associate a user data tag with an atom. The atom should be in exclusively locked state and currently being owned by the caller.
atom Atom, as returned by TLockAtom data User data tag to be associated
olddata Previous data tag
The return value and data argument were of type TAPTR in Exec 1.0. This has been fixed in 2.0. This change could break binaries written for Exec 1.0 on some architectures.
exec : TGetAtomData | Toc |
TGetAtomData - Query an atom's data tag
data = TExecGetAtomData(TExecBase, atom) TTAG TAPTR TAPTR data = TGetAtomData(atom) TTAG TAPTR
Query an atom's user data tag. The atom should be in locked state and currently being owned by the caller.
atom Atom, as returned by TLockAtom
data Atom's user data
The return value was of type TAPTR in Exec 1.0. This has been changed in 2.0.
exec : TCreatePool | Toc |
TCreatePool - Create a memory pool
pool = TExecCreatePool(TExecBase, tags) TAPTR TAPTR TTAGITEM* pool = TCreatePool(tags) TAPTR TTAGITEM*
Create a memory pool. A pool is an allocator that groups small allocations into larger ones. All pending allocations made from a pool will be returned to the pool's underlying memory manager once the pool is being destroyed with a call to teklib:TDestroy.Pools grow and shrink on demand. Two parameters constitute their behavior:
- Pudsize is the size of a 'puddle', i.e. a regular chunk of memory that will be allocated from an underlying memory manager when a request cannot be satisfied from the current set of puddles. Many small allocations can fit into a puddle.
- Thressize is the maximum size of allocations that go into regular puddles. Allocations larger than that will go into puddles of their own. Thressize must be less or equal pudsize. Both pudsize and thressize can be supplied in taglist arguments and remain constant during a pool's lifetime. By default, though, TEKlib pools try to determine appropriate settings for pudsize and thressize during a pool's lifetime and adapt these parameters dynamically. Pools can be useful for sections of code that mainly deal with many objects of relatively constant sizes. Allocations in a pool are more tightly packed and on smaller boundaries than general-purpose allocations.
tags Pointer to an array of tag items
TPool_MMU, (TAPTR)Pool's underlying memory manager - this is where puddles will be allocated from.TPool_PudSize, (TUINT)Initial size of puddles [bytes]. When TPool_AutoAdapt is enabled then this value can change during a pool's lifetime. Default: 1024TPool_ThresSize, (TUINT)Initial threshold size for allocations that go into regular puddles [bytes]. This value must be less than or equal pudsize. When TPool_AutoAdapt is enabled then this value can change during a pool's lifetime. Default: 256TPool_AutoAdapt, (TBOOL)Use a simple load analysis to adapt a pool's pudsize and thressize to the requirements during its lifetime. Currently thressize tends to 4 times the average size of allocations and pudsize tends to 8 times of thressize. Default: TTRUETMem_LowFrag, (TBOOL)Use an allocation strategy that may help to reduce a pool's internal fragmentation, at the cost of some extra performance. This is also known as the 'best match' strategy. The default is the 'first match' strategy. default: TFALSE
pool Pointer to a pooled allocator or TNULL if failed
- Pools are not inherently safe to use from multiple tasks at the same time. If multiple tasks wish to access it simultaneously then the pool must be protected with a locking mechanism.
- A pool itself can serve the underlying allocator for a memory manager. See TCreateMMU for details.
- One of the possible benefits of pools is that the efficiency of TReallocPool is the same on all platforms, while the efficiency of TRealloc with a TNULL memory manager can significantly differ.
- As a rule of thumb, use a general-purpose allocator when the exact requirements, costs and benefits of a special allocator cannot be estimated.
exec : TAllocPool | Toc |
TAllocPool - Allocate from a pool
mem = TExecAllocPool(TExecBase, pool, size) TAPTR TAPTR TAPTR TUINT mem = TAllocPool(pool, size) TAPTR TAPTR TUINT
This function allocates a block of memory from a pool. A Pointer to the allocated block of memory is returned, or TNULL when the request cannot be satisfied.
pool Pointer to a pool created with TCreatePool size Size of the allocation [bytes]
mem Pointer to a block of memory, or TNULL if out of memory
exec : TFreePool | Toc |
TFreePool - Return memory to a pool
TExecFreePool(TExecBase, pool, mem, size) TAPTR TAPTR TAPTR TUINT TFreePool(pool, mem, size) TAPTR TAPTR TUINT
Return a block of memory to the pool from which it was allocated.
pool Pointer to the pool the allocation was made from mem Block of memory to be freed size Size of the allocation
exec : TReallocPool | Toc |
TReallocPool - Resize a pool allocation
newmem = TExecReallocPool(TExecBase, pool, oldmem, oldsize, newsize) TAPTR TAPTR TAPTR TAPTR TUINT TUINT newmem = TReallocPool(pool, oldmem, oldsize, newsize) TAPTR TAPTR TAPTR TUINT TUINT
Resize a block of memory that has been allocated from a pool. If newsize is zero then the allocation will be freed, and the result will be TNULL. If oldmem is TNULL and oldsize is zero then a new block will be allocated.
pool Pointer to the pool the allocation was made from oldmem Pointer to memory allocated oldsize Previous size of the allocation newsize New size for the allocation
newmem Pointer to resized block, or TNULL if failed
- Reallocation may require that the given block of memory needs to be moved in memory and pointers to this area may become invalid.
exec : TDoExec | Toc |
TDoExec - Run an Execbase context
success = TExecDoExec(TExecBase, tags) TBOOL TAPTR TTAGITEM* success = TDoExec(tags) TBOOL TTAGITEM*
Run or initialize an Exec context. TDoExec services module opens, module loading, task creation and atom lookups. This function is of any use only for implementors of startup libraries.TDoExec is expected to be called in a task previously initialized by the caller using TCreateSysTask. The name of the task in which it is called determines what kind of service will be provided:
- If the calling task's name is TTASKNAME_EXEC ("exec") then this function will serve module opens, task creation and atom lookups, requested through the message port execbase->texb_ExecPort. It returns to the caller when it receives the signal TTASK_SIG_ABORT.
- If the name is TTASKNAME_RAMLIB ("ramlib") then this function will serve requests for module loading, submitted to the task's userport. It returns when it receives the signal TTASK_SIG_ABORT.
- If the name is TTASKNAME_ENTRY ("entry") then this function will perform initializations that qualify the current context as TEKlib's initial application task.
tags Pointer to an array of tag items
Currently none defined
success Boolean
exec : TPutIO | Toc |
TPutIO - Put I/O request to a device, asynchronously
TExecPutIO(TExecBase, ioreq) TAPTR struct TIORequest * TPutIO(ioreq) struct TIORequest *
This function puts an I/O request to the device or handler specified in the ioreq->io_Device field.TPutIO clears the TIOF_QUICK flag from the ioreq->io_Flags field, indicating that it prefers asynchronous execution, and forwards the request through the "BeginIO"-vector of the device.Whether or not the request will be executed asynchronously remains transparent to the caller. After the request has been processed, it will return to the replyport specified in ioreq->io_ReplyPort and cause the replyport's signal to show up in the caller's task. Always use TWaitIO to synchronize on completion of an I/O request and its removal from the replyport queue.
iorequest I/O request message to be processed
exec : TWaitIO | Toc |
TWaitIO - Wait for completion of an I/O request
error = TExecWaitIO(TExecBase, ioreq) TINT TAPTR struct TIORequest* error = TWaitIO(ioreq) TINT struct TIORequest*
This function waits for an I/O request to complete and unlinks it from its ioreq->io_ReplyPort. If the request has already finished or was processed synchronously then TWaitIO drops through immediately.
iorequest I/O request message to be processed
error Contents of the iorequest's io_Error field A return value of zero indicates success.
exec : TDoIO | Toc |
TDoIO - Perform an I/O request synchronously
error = TExecDoIO(TExecBase, ioreq) TINT TAPTR struct TIORequest * error = TDoIO(ioreq) TINT struct TIORequest *
This function performs an I/O request and waits for completion. TDoIO indicates that it prefers synchronous execution by setting the TIOF_QUICK flag in the ioreq->io_Flags field before the request is forwarded through the "BeginIO"-vector of the device.A return value of zero indicates success.
iorequest I/O request message to be processed
error Contents of the iorequest's io_Error field
exec : TCheckIO | Toc |
TCheckIO - Test if an I/O request is complete
complete = TExecCheckIO(TExecBase, ioreq) TBOOL TAPTR struct TIORequest * complete = TCheckIO(ioreq) TBOOL struct TIORequest *
This function tests if an I/O request has been completed and returns its status to the caller.Note that a finished I/O request still needs to be removed from the replyport's queue using TWaitIO.
iorequest I/O request message to be processed
complete - Boolean
exec : TAbortIO | Toc |
TAbortIO - Try to abort an I/O request
error = TExecAbortIO(TExecBase, ioreq) TAPTR struct TIORequest* error = TAbortIO(ioreq) struct TIORequest*
Ask a device to abort an I/O request that has been forwarded to a device using TPutIO. Note that abortion is a service that may or may not be granted by the addressed device or handler. You must in no way rely on successful abortion and you still have to synchronize on the I/O request properly using TWaitIO.
iorequest I/O request message to be processed
error 0 if the request for abortion succeeded -1 if the request is still pending
exec : ABOUT | Toc |
TEKlib Exec module API documentation
$Id: exec.html,v 1.15 2005/09/13 01:09:28 tmueller Exp $
$Log: exec.html,v $ Revision 1.15 2005/09/13 01:09:28 tmueller added non-inline calls to synopsis Revision 1.7 2005/07/07 01:43:48 tmueller fixed TGetExecBase sectionRevision 1.6 2005/06/29 21:41:02 tmueller minor fixesRevision 1.5 2005/06/22 14:12:15 tmueller typos fixedRevision 1.4 2005/06/22 14:00:57 tmueller improvements, updates, cleanupRevision 1.3 2005/06/20 17:28:37 tmueller updatedRevision 1.2 2005/06/20 12:39:10 tmueller converted using gendoc.luaRevision 1.1 2005/06/19 20:42:21 tmueller addedRevision 1.9 2004/06/11 17:49:22 tmueller API change in TLockAtom documentedRevision 1.8 2004/04/18 16:27:06 tmueller Added notes about API changes in Exec and Util between 1.0 and 2.0Revision 1.7 2004/04/18 13:57:53 tmueller arguments in parseargv, atomdata, gettag changed from TAPTR to TTAGRevision 1.6 2004/01/31 11:32:15 tmueller Typos fixed, slightly improved wordingRevision 1.5 2004/01/13 02:12:32 tmueller CosmeticRevision 1.4 2003/12/13 14:13:51 tmueller More info about pooled allocators addedRevision 1.3 2003/12/12 03:48:29 tmueller Major rework, clarifications, better wordingRevision 1.2 2003/12/11 14:54:42 tmueller OverhaulRevision 1.1.1.1 2003/12/11 07:17:37 tmueller Krypton importRevision 1.8 2003/10/29 02:03:30 tmueller Autodocs share a common topology now: 0_ABOUT, 1_INDEXRevision 1.7 2003/10/28 21:26:09 tmueller CosmeticRevision 1.6 2003/10/26 01:37:45 tmueller Documented TDoIO, TPutIO, TWaitIO, TAbortIO, TCheckIO, TDoExec.Revision 1.5 2003/10/25 04:10:03 tmueller Restructuring, typo fixes and cosmetic changesRevision 1.4 2003/10/20 14:21:01 tmueller typos fixedRevision 1.2 2003/09/02 20:08:59 tmueller minor fixesRevision 1.1.1.1 2003/03/08 18:28:40 tmueller Import to new chrooted pserver repository.Revision 1.3 2003/02/02 20:50:21 tmueller TLockAtom documentation updatedRevision 1.2 2002/12/03 05:25:46 bifat TNULL task argument is now valid to TAllocTaskRevision 1.1.1.1 2002/11/30 05:15:33 bifat import
exec : Table of contents |
- ABOUT
- Index
- Internal
- Locking
- Memory
- Modules
- Ports
- TAbortIO
- TAckMsg
- TAlloc
- TAlloc0
- TAllocMsg
- TAllocMsg0
- TAllocPool
- TAllocSignal
- TCheckIO
- TCloseModule
- TCopyMem
- TCreateLock
- TCreateMMU
- TCreatePool
- TCreatePort
- TCreateSysTask
- TCreateTask
- TDoExec
- TDoIO
- TDropMsg
- TFillMem
- TFillMem32
- TFindTask
- TFree
- TFreePool
- TFreeSignal
- TGetAtomData
- TGetExecBase
- TGetHALBase
- TGetMMU
- TGetMsg
- TGetPortSignal
- TGetSize
- TGetSyncPort
- TGetTaskData
- TGetTaskMMU
- TGetUserPort
- TLock
- TLockAtom
- TOpenModule
- TPutIO
- TPutMsg
- TRealloc
- TReallocPool
- TReplyMsg
- TSendMsg
- TSetAtomData
- TSetSignal
- TSetTaskData
- TSignal
- TUnlock
- TUnlockAtom
- TWait
- TWaitIO
- TWaitPort
- Tasks
Generated Mon Sep 12 21:26:50 2005 from exec.doc