Kernel

In order to gain access to a block of public memory, the AccessMemory() function must be called to page the block into your task's memory space. If the MemoryID is valid and the block is available, a valid address pointer. will be returned that you may use for direct read/write operations. For your convenience, this function may also be used to resolve the memory addresses of private memory block IDs.

Public memory blocks should never be locked for long periods of time. You must match all locks that you make with calls to ReleaseMemory() inside a reasonable time frame. Always keep in mind that other tasks may be waiting to gain access to memory blocks that you lock.

Please note that the address that is returned is specific to your task only and cannot be passed to any other task in the system.

This function is provided so that tasks can gain temporary exclusive access to public objects. It is specially designed to prevent more than one task from having access to a specific object at any given moment. The AccessObject() function also works on private objects for reasons of consistency.

Once you call this function, it will immediately attempt to page the object's address space into your task. If it cannot do this, the function will wait until the object becomes available. This must occur within the amount of time specified by the Milliseconds argument. If the time runs out, the function will return with an ERR_TimeOut error code. If successful, ERR_Okay will be returned and you will have exclusive access to the object through the address pointed to in the Result variable. Once you are done with the object, call ReleaseObject() so that other tasks can access it.

If this function fails, the Result variable will be automatically set to a NULL pointer on return.

The AccessSemaphore() function will give your task access to a semaphore once it becomes available. If the semaphore is available immediately then the function will return instantly. If other processes have blocked the semaphore through their usage, your task will be put to sleep for up to the time specified in the Timeout parameter. If you do not specify a Timeout, then the function will return immediately with an ERR_Timeout error.

Each time you call AccessSemaphore(), the system will try to 'block' the semaphore by default, which means you get exclusive access to the resource represented by the semaphore. If you only need non-blocking access to the semaphore, you must use the SMF_NONBLOCKING flag. In this mode, the system will decrement the semaphore counter by 1 and return. If the semaphore counter reaches a value of zero then the function will wait until one of the accessing processes releases its hold on the semaphore.

You must match each call to AccessSemaphore() with a call to the ReleaseSemaphore() function.

This function is the key entry point for executing actions and method routines. An action is a predefined function call that can be called on any object, while a method is a function call that is specific to a particular object type. You can find a complete list of available actions and their associated details in the Action List document. If an object supports methods, they will be listed in the object's class document.

Here are two examples that demonstrate how to make an action call. The first performs an initialisation, which does not require any additional arguments. The second performs a move operation, which requires three additional arguments to be passed to the Action() function:

   1. Action(AC_Init, Picture, NULL);

   3. struct acMove move;
      move.XChange = 30;
      move.YChange = 15;
      move.ZChange = 0;
      Action(AC_Move, Window, &move);

If the target object does not support the action code that you have specified, an error code of ERR_NoSupport will be returned. If you need to test an object to see if it supports a particular action, use the CheckAction() function.

If you need to send an action to an object that does not belong to your task space, use the ActionMsg() function. If you're in a situation where you only have an object ID and are unsure as to whether or not the object is in your task space, use ActionMsg() anyway as it will divert to the Action() function if the object is local.

If you are writing a class and need to know how to add support for a particular action, look it up in the Action Support Guide.

If you need a dynamic list of all the actions supported by the object kernel, including information on ID's, names, arguments and structure sizes, use the ActionList() function. This function will return an array that is arranged into a look-up table, sorted by action ID. The ActionTable structure is defined as follows:

   struct ActionTable {
      STRING Name;
      struct FunctionField *Args;
      LONG Size;
   };

The Name field specifies the name of the action. The Args field refers to the action's argument definition structure, which lists the argument names and their relevant types. This is matched by the Size field, which indicates the byte-size of the action's related argument structure. If the action does not support arguments, the Args and Size fields will be set to NULL. Here are two argument definition examples:

   struct FunctionField argsCopyData[] = {
      { "Destination", ARG_LONG  },
      { NULL, NULL }
   };

   struct FunctionField argsResize[] = {
      { "Width",  ARG_DOUBLE },
      { "Height", ARG_DOUBLE },
      { "Depth",  ARG_DOUBLE },
      { NULL, NULL }
   };

The argument types that can be set by actions are limited to those listed in the following table:

ActionMsg() provides the necessary functionality to execute an action on any shared object that does not reside within your task space. The function works first by testing the object to see if it it belongs to your task space, or someone else's task space. If the object is yours then the action will be called immediately, as if Action() was called under normal circumstances. Otherwise, the action call will be sent to the object's owner as a message and the function will immediately return to your program.

Once an action has been sent, you need to work on the assumption that its owner will respond to the message and execute the action. If the Task does not respond, then likely causes may include a task crash, buggy programming or an extended busy period.

There is one exception to the rule: In cases where an action or method returns a result (e.g. the Read and Write actions do this), the ActionMsg() function will actually ask the other Task to send back the result information. This causes the function to sleep for a short period of time until it receives the result information from the other Task. By doing this, the normal behaviour that would be expected of an action that returns results is preserved.

This function is identical to the Action() function in every respect, except that it allows you to send action arguments as tags rather than in a structure. Here are a few examples:

   ActionTags(AC_Resize, Object, 100, 300, 200);
   ActionTags(MT_Rename, Object, "athene:documents.txt");

Whether you choose to use ActionTags() or Action() to make your action calls is a matter of personal preference. However, be aware that ActionTags() does not support actions or methods that return results in the argument structure - e.g. Read and Write actions are not supported.

The AllocMemory() function is used to allocate blocks of memory from the system memory pool. To allocate a new block you need to specify its Size, allocation Flags and Address and/or MemoryID arguments to store references to the allocation. Here is an example:

   APTR Address;

   if (AllocMemory(1000, MEM_DATA, &Address, NULL) IS ERR_Okay) {
      ...
      FreeMemory(Address);
   }

A number of flag definitions are available that affect the memory allocation process. They are:

You will notice that you have the option of receiving the memory allocation as an address pointer and/or as a unique memory ID. When allocating private memory, you can generally just accept an address result and drive the MemoryID argument to NULL. However when allocating public memory, you should always retrieve the MemoryID, and optionally the Address pointer if you need immediate access to the block.

If the block is allocated as private and you retrieve both the MemoryID and Address pointer, or if the allocation is public and you choose to retrieve the Address pointer, an internal call will be made to AccessMemory() to lock the memory block and resolve its address. This means that before freeing the memory block, you must make a call to the ReleaseMemory() function to remove the lock, or it will remain in memory till your Task is terminated.

Memory that is allocated through AllocMemory() is automatically cleared with zero-byte values. When allocating large blocks it may be wise to turn off this feature - you can do this by setting the MEM_NOCLEAR flag.

The AllocSemaphore() function is used to create new semaphores and join existing ones. To create a simple semaphore for private usage, you only need to provide this function with a return value in the Semaphore parameter. If you want to share a semaphore with other processes, you need to give it a unique name limited to 15 characters. The Value argument is optional and only needs to be used if you need more complex signalling for your program.

Semaphores are most commonly used to control access to shared resources, typically in shared memory areas. For instance, if you create a shared memory area for read/write operations between tasks, you need a control system to prevent the tasks from writing to the memory at the same time (allowing multiple read access is usually non-harmful and quite convenient). Using a semaphore is perfect for controlling this type of situation.

For a simple blocking semaphore, you should set a value of 1 in the Value parameter. If you want to allow multiple processes to read from the resource then you should set the Value much higher - 100 or more. In this mode, there are two ways for processes to access the semaphore - blocking and non-blocking mode. Either type of access is achieved through the AccessSemaphore() function. Blocking mode is the default and will grant you full access to the resource if it succeeds. Non-blocking access grants you limited access to the resource - typically considered 'read only' access. Multiple processes can have non-blocking access at the same time, but only one process may have access when blocking mode is required. If you set a value of 100, then the number of non-blocking accesses will be limited to 100 processes. Any more processes than this wishing to use the semaphore will need to wait until some of the accesses are released. If 50 processes currently have read access and a new process requires blocking access, it will have to wait until all 50 read accesses are released. The specifics of this are discussed in the documentation for AccessSemaphore() and ReleaseSemaphore().

The handle returned in the Semaphore argument is global, so if you want to secretly share an anonymous semaphore with other processes, you may do so if you pass the handle to them. The other processes will still need to call AllocSemaphore() to register their interest, but they need to add the SMF_EXISTS Flag and also pass the semaphore handle to this function via the Semaphore parameter.

To free a semaphore after you have allocated it, call the FreeSemaphore() function. It is possible to call AllocSemaphore() with the same Name as many times as you like because the calls will nest, but you must match them all with FreeSemaphore() calls. A semaphore will not be completely freed from the system until all processes that have gained access drop their control of the semaphore.

This function generates unique ID's that can be used for unregistered classes. ID's that are allocated through this function are permanent for the duration that the system is active. There is no need to free allocated class ID's when you are finished with them.

This function generates unique ID's that can be used in certain areas of the object kernel. Simply tell this function the type of unique ID that you want to retrieve, and it will pass a unique ID back to you. The following ID types are currently supported:

ID allocations are permanent, so there is no need to free an allocated ID when you are finished with it.

This function checks if a particular object supports a given action or method ID. To check if a Picture object supports the Query action for instance, a code segment such as this would be sufficient:

   if (CheckAction(Picture, AC_Query) IS ERR_Okay) {
      ...
   }

If you need to know whether or not a specific memory block still exists, you can check by using the CheckMemoryExists() function. Simply provide it with the ID of the block that you are interested in and it will return an error code of ERR_Okay if it is in the system at the time of calling.

The CheckObjectExists() function checks for the existence of an object within the system. CheckObjectExists() is commonly used to check for the presence of shared objects, which can be removed from the system at any time by other tasks.

This function allows you to check for an object either by ID or name. Please note that in the case of name checking, it is possible for multiple objects with the same name to exist at the time of calling this function.

Use the ClearMemory() function when you need to clear a block of memory as efficiently as possible.

This function allows you to make a duplicate of any memory block that has been allocated from AllocMemory(). The new memory block will be completely identical to the block you have specified, except for the type of memory, which you can alter through the Flags argument. The contents of the original memory block will be copied over to the duplicate block.

You have the option of receiving the cloned memory block as an address pointer and/or as a unique memory ID. When allocating private memory, you can request an address result only and leave the MemoryID argument as NULL. However when cloning public memory, you should always retrieve the MemoryID, and optionally the Address pointer if you need immediate access to the cloned block.

If the block is cloned as private memory and you retrieve both the MemoryID and Address pointer, or if the allocation is public and you choose to retrieve the Address pointer, an internal call will be made to AccessMemory() to lock the memory block. This means that before freeing the memory block, you must make a call to the ReleaseMemory() function to remove the lock, or it will remain in memory.

Remember to free the cloned memory block when you are finished with it.

CreateObject() is an enhanced version of the NewObject() function. It performs the same activity as NewObject(), but will also set field values and initialise the object automatically for you. In other words, this function is provided for your convenience, and is not an integral part of the system's object management services.

Please refer to the NewObject() function for information on the allocation of new objects. Also see the SetFields() function for an outline of the formatting details of the tag arguments.

The CurrentContext() function returns a pointer to the object that has the current context. In order for an object to have the context of the current Task, it must have been successfully set from the SetContext() function.

CurrentContext() is typically used to find out what object is currently receiving resource allocations. It is useful in improving the management of resources that your code may be allocating.

The CurrentTaskID() function returns the object ID of the Task that is making the call - i.e. "you". Task objects' are used for storing data that is specific to a running program. Refer to the Task class for details.

There are some cases where CurrentTaskID() can return a NULL value. This can occur if there is no related Task object, or if the Task object has been corrupted. For this reason it is recommended that calls to CurrentTask() are enclosed within an IF statement.

If there is a legitimate circumstance where there is no current task (for example if this function is called during kernel initialisation) then the "system task" may be returned (the system task controls and maintains the kernel).

It is also possible to retrieve a direct pointer to the task's object structure by calling the CurrentTask() function. This saves on the time required to access and release the task object when using ID's.

The DPrintF() function follows the same functionality and rules as the ANSI printf() function. The only difference is that it prints directly to the debug window. Due to internal limits your string is limited to a total of 256 bytes output, although you should keep everything within 80 bytes to avoid running onto a second row. You can supply a maximum amount of 5 '%' parameters to this function.

The following example will print the default width of a Screen object to the debug window.

   if (NewObject(ID_SCREEN, NULL, &Screen, NULL) IS ERR_Okay) {
      if (Action(AC_Init, Screen, NULL)) {
         DPrintF("Demo:","The width of the screen is: %d", Screen->Width);
      }
      Action(AC_Free, Screen, NULL);
   }

This function provides a switch for turning debug messages on and off. This is useful for turning off messages just before running intense looping sequences. It is also used to dynamically alter the amount of detail printed to the debugger, using the Level argument.

Calls to this function will nest according to the State argument, so if the function is called twice with State set to FALSE, then it must be called twice again with State set to TRUE to reenable debugging.

The DeregisterFD() function is used to de-register file descriptors that you have registered via the RegisterFD() function. Once removed, the task will stop monitoring the file descriptor for activity.

The FastFindObject() function is an optimised implementation of the FindObject() function. You can use it to search for objects in the system by their name and/or class. Unlike FindObject(), which will return an allocated memory block that lists all of the objects that were found, FastFindObject() requires that you provide a memory area to write the results to. This saves the cost of allocation time, which can be expensive in some situations.

The following code example is a typical illustration of this function's use. It finds the most recent object created with a given name:

   OBJECTID SystemPointerID;
   FastFindObject("SystemPointer", ID_POINTER, &SystemPointerID, 1, NULL);

If FastFindObject() cannot find any objects with the name that you are looking for, it will return an error code.

The list is sorted so that the oldest private object is placed at the start of the list, and the most recent public object is placed at the end. This will assist you in situations where you may be looking for the oldest or youngest object to have the particular name that you have searched for. Preference is also given to objects that have been created by your own task, so foreign objects are also pushed towards to the top of the list.

This function is used to search the system for all members of a specific class. If you wanted to search for all members of the Picture class for example, the following code could be used:

   OBJECTPTR Class;

   Class = NULL;
   while (Class = FindClass(ID_PICTURE, Class)) {
      ...
   }

If a matching class is found in the system, it will be returned immediately. The base class is always returned first, while subsequent calls to this function will return sub-classes. Once all of the matching classes have been discovered, a NULL pointer will be returned to indicate an end to the search.

The FindObject() function is used to search for objects in the system by name and class type. If the function cannot find any object with the name or class that you are looking for, then it will return an error code. If it does find one or more matching objects, then a complete list of them will be returned in an allocated memory block.

The List is sorted so that the oldest object is placed at the start of the list, and the most recent is placed at the end. This will assist you in situations where you may be looking for the oldest or youngest object that has the particular name that you have searched for.

The List is terminated with a NULL entry.

The List is returned as an allocated memory block. Please call FreeMemory() on the List pointer so that it is not left in memory after you have used it.

The FindPrivateObject() function is provided as a simple implementation of the FastFindObject() function. This implementation is specifically limited to finding private objects by name only. It is capable of returning only one object address in its search results. Unlike FastFindObject(), this function returns directly accessible object addresses that may be used immediately after a successful search.

If multiple objects with the same name exists, the most recently created object will be returned by this function.

If you require more advanced functionality for object searches, please use the FastFindObject() function.

Use the Forbid() function to aggressively lock out the kernel's shared memory and shared object services. This allows you to use the shared areas of the object kernel without encountering race conditions caused by other tasks trying to access the same areas. Calls to Forbid() must be followed with a call to Permit() to undo the lock.

Due to the powerful nature of this function, you should only ever use it in small code segments and never in areas that involve communication with other tasks. Locking for extended periods of time (over 4 seconds) may also result in your task being automatically killed off by the system.

Multiple calls to Forbid() will nest.

This function frees memory areas allocated from AllocMemory(). Crash protection is incorporated into various areas of this function. If the memory header or tail is missing from the block, then it is assumed that a routine has has over-written the memory boundaries, or you are attempting to free a non-existant allocation. Such problems are immediately reported to the system debugger. Bear in mind that it does pay to save your development work if such a message appears, as it indicates that important memory areas could have been destroyed.

For speed reasons, this function only supports private memory. If you wish to free a public memory block, you will need to use the FreeMemoryID() function instead.

When a public memory block is no longer required, it can be freed from the system with this function. The action of freeing the block will not necessarily take place immediately - if another Task is using the block for example, deletion cannot occur for safety reasons. In a case such as this, the block will be marked for deletion and will be freed once all Tasks have stopped using it.

The FreeSemaphore() function is used to deallocate semaphores when you are no longer in need of them. You must call FreeSemaphore() for each time that you have called the AllocSemaphore() function. If you still have locks on the semaphore at the time that you call this function, the semaphore will not be removed from the system until those locks are released.

A semaphore is never completely removed from the system until all processes have given up their allocations against the semaphore.

This function can be used on any valid object ID to retrieve the ID of its class. This is the quickest way to retrieve the class of an object without having to gain exclusive access to the object first.

Please note that if you already have access to an object through an address pointer, the quickest way to learn of its class is to read the ClassID field in the object header.

The GetField() function is used to read field values from objects. You don't need to know anything about the object structure in order to read information from it - you just need to know what field you want to read.

The following code segment illustrates how to read values from an object:

   LONG XCoord, YCoord;

   GetField(Object, FID_XCoord, FT_LONG, &XCoord);
   GetField(Object, FID_YCoord, FT_LONG, &YCoord);

As GetField() is based on field ID's that reflect field names ("FID's"), you will find that there are occasions where there is no reserved ID for the field that you wish to read. To convert field names into their relevant IDs, call the ResolveFields() function. Reserved field ID's are listed in the "system/fields.h" include file.

When reading a field you are required to make an educated guess as to its type, in order to prevent a type mismatch from occurring. For instance, reading a coordinate field would mean that the field is a number, so you should read the field as a numeric type rather than choosing a pointer type.

Available field types are listed in the following table:

The variable that you point to in the Result argument must match the ResultType that you have specified, or you will risk crashing your program code.

The GetFieldVariable() function is used in situations where you need to retrieve the value of a field without knowing the field's type or any details beyond the field name. Although simple to use, it is the slowest of the field retrieval instructions because the field's value must be converted from its original type into a string.

You need to provide a buffer that is large enough to hold the expected value. If the buffer is not large enough then the resulting value will be cut short. 256 bytes is considered a large enough buffer for most occasions. In more extreme circumstances, a buffer as large as 1kb may be needed.

This function does not support pointer based fields as they cannot be translated, although an exception is made for string field types.

This function can be used to grab the values of multiple fields in a single function call. It is primarily provided to give a speed increase over calling the GetField() function multiple times. The arguments passed to this function are tag-based and must be terminated with a TAGEND marker, as shown in the following example:

   LONG Width, Height;

   GetFields(Screen,
      FID_Width|TLONG,  &Width,
      FID_Height|TLONG, &Height,
      TAGEND);

The field ID's that you specify must be logically or'd with tag definitions that indicate the type of values that you want to get from each field. For instance, if want to retrieve a field in floating point format, then you must use the TFLOAT tag and supply a pointer to a FLOAT variable. Please note that failing to set the tag values correctly can often cause a program to crash.

The recognised tag types are TPTR, TSTRING, TLONG, TLARGE, TFLOAT, and TDOUBLE.

If the GetFields() does not return an ERR_Okay code, you should work on the assumption that all of the field settings failed, meaning that your routine should abort in most cases. This function aborts immediately and makes no attempt to 'salvage' any other fields that may be left in the list, or undo earlier field settings that were successful.

For information on the field retrieval process, refer to the GetField() function.

The GetMessage() function is used to read messages that have been stored in message queues. You can use this function to read the next immediate message stored on the queue, or the first message on the queue that matches a particular Type. It is also possible to call this function in a loop to clear out all messages, until an error code other than ERR_Okay is returned.

Messages will often (although not always) carry data that is relevant to the message type. To retrieve this data you need to supply a buffer, preferably one that is large enough to receive all the data that you expect from your messages. If the buffer is too small, the message data will be cut off to fit inside the buffer.

Message data is written to the supplied buffer with a Message structure (struct Message), which is immediately followed up with the actual message data. The message structure includes the following fields:

The object kernel allows names to be assigned to objects for the purpose of easy identification. Naming is also important for scripts and identification from a user point of view. Calling GetName() will return the name of any object that you have access to. If the target object has not been assigned a name, then you will receive a null-string.

The length of an object name is limited to the value indicated by the MAX_NAMELEN definition in the "main.h" include file.

This function can be used on any valid object ID to retrieve the unique ID of its owner. This is the quickest way to retrieve the owner of an object without having to gain exclusive access to the object first.

Please note that if you already have access to an object through an address pointer, the quickest way to learn of its owner is to read the OwnerID field in the object header.

The GetResource() function is used to retrieve miscellaneous resource ID's that are either global or local to your task. To retrieve a resource you need to make a reference to it with the Resource parameter. Currently the following resource ID's are available:

The ListChildren() function provides the necessary means for listing an object's children in a single function call.

You need to provide an empty array of ChildEntry structures in the List argument, so that this function has an area to write the results to. The Count argument must point to a longword that indicates the size of the array that you have supplied. Before returning, the ListChildren() function will update the Count variable so that it reflects the total number of children that were written to the array.

The definition of the ChildEntry structure is as follows:

   struct ChildEntry {
      OBJECTID ObjectID;
      LONG ClassID;
   };

The ClassID field is included to assist you in finding specific object types.

Objects that are specially marked with the CHILD flag are not returned in the resulting list; such objects are considered to be private extensions of the targetted parent.

The ListMemory() function is typically used for debugging and memory monitoring purposes. It is capable of returning a complete list of public memory blocks, or all private blocks that are local to your task.

The function will return the list by allocating an array and storing it in the variable provided by the List argument. The ListMemory structure used to create the array contains the following fields:

The ListMemory array is terminated with a final entry that has all fields driven to NULL.