<--- Cannot embed stylesheet: [Errno 2] No such file or directory: '../../../../aros.css' --->

Dataspace.mui

MUIA_Dataspace_Pool

Function

Select the Exec pool used for record allocation. This is an
initialization-only APTR attribute. Omission or NULL creates an owned
pool using CreatePool(0, 4096, 4096); construction fails if that fails.
A non-NULL value is borrowed and is not deleted by Dataspace.

Notes

Keep a supplied pool alive until the Dataspace object is disposed of.
The object's semaphore protects its own record methods, not unrelated
users of a shared pool. Coordinate those users separately.
Disposal deletes an owned pool, or frees the object's records from a
borrowed pool.

See Also

MUIC_Dataspace, MUIM_Dataspace_Clear

MUIC_Dataspace

Superclass

Semaphore.mui

Description

Store copied byte records under nonzero ULONG identifiers. The class
supports insertion/replacement, lookup, removal, and an IFF record format.
Storage comes from a caller-supplied pool or an internally created pool.

Public record methods take the inherited semaphore. Find holds a shared
lock only during the search; mutation and IFF methods take an exclusive
lock. Object disposal is not synchronized by these method locks. The
caller must keep the object alive throughout all operations and uses of
borrowed record pointers.

Bugs

Merge is a stub. Clear frees records without resetting the list links.
ReadIFF can return success after an incomplete import. Consult the method
entries before relying on these operations.

See Also

MUIA_Dataspace_Pool, MUIM_Dataspace_Add, MUIM_Dataspace_Find

MUIM_Dataspace_Add

Synopsis

IPTR result = DoMethod(obj, MUIM_Dataspace_Add, (IPTR)data, len, id);

Function

Copy a record into the dataspace. A record with the same identifier is
replaced after new storage has been allocated. The new record is appended
to the list, including when it replaces an existing record.

Inputs

data - Non-NULL pointer to at least len readable bytes.
len - Positive LONG byte count that fits the record allocation, including
the internal node header.
id - Nonzero ULONG identifier.

Result

1 after insertion; 0 for NULL data, a nonpositive length, id == 0,
or allocation failure. Those failures leave an existing record intact.

Notes

The caller retains its input storage. The dataspace owns the copy until
replacement, removal, clearing, or disposal. Do not use the old payload
of the same identifier as input: replacement frees that record before
CopyMem() reads the supplied bytes. Copy such data to separate storage
first. The dispatcher holds an exclusive semaphore lock.

See Also

MUIM_Dataspace_Find, MUIM_Dataspace_Remove

MUIM_Dataspace_Clear

Synopsis

IPTR result = DoMethod(obj, MUIM_Dataspace_Clear);

Function

Free each record allocation while holding the exclusive semaphore.

Inputs

No arguments beyond MethodID.

Result

Always 1 after the loop completes.

Bugs

The implementation does not unlink the freed records or reinitialize
the list. After clearing a nonempty dataspace, its list contains dangling
pointers. The return value does not establish a reusable empty object.
Subsequent record operations or borrowed-pool disposal can access freed
storage. Do not use this method to reset a live nonempty dataspace.

See Also

MUIM_Dataspace_Remove, MUIA_Dataspace_Pool

MUIM_Dataspace_Find

Synopsis

APTR data = (APTR)DoMethod(obj, MUIM_Dataspace_Find, id);

Function

Search the record list for an identifier and return its payload.

Inputs

id - ULONG identifier to find.

Result

Borrowed pointer to the stored bytes, or NULL if no record matches.
No length is returned; the caller must know the record format.

Notes

Do not free the pointer. Replacement of that identifier, removal,
clearing, or disposal invalidates it. The dispatcher releases its shared
lock before returning, so the result alone is not protected against
concurrent changes. Keep the object alive and prevent mutation throughout
the use of its payload. For concurrent access, hold the inherited
semaphore exclusively around both lookup and payload use, then release it.

See Also

MUIM_Dataspace_Add, MUIM_Semaphore_Obtain, MUIM_Semaphore_Release

MUIM_Dataspace_Merge

Synopsis

IPTR result = DoMethod(obj, MUIM_Dataspace_Merge, (IPTR)dataspace);

Function

Return 1 without copying or changing records. This is a stub.

Inputs

dataspace - Declared source-object argument; ignored.

Result

Always 1. This value does not indicate that a merge occurred.

Notes

The dispatcher takes and releases the destination object's exclusive
semaphore even though the method body does no work.

See Also

MUIM_Dataspace_Add

MUIM_Dataspace_ReadIFF

Synopsis

LONG result = (LONG)DoMethod(obj, MUIM_Dataspace_ReadIFF, (IPTR)handle);

Function

Read bytes from the current IFF chunk and interpret successive records
as a big-endian 32-bit identifier, a big-endian 32-bit payload length,
and that many payload bytes. Pass each complete record to MUIM_Dataspace_Add.
Existing records are retained except where an imported identifier replaces
them. Payload bytes are copied without byte-order conversion.

Inputs

handle - Valid IFF handle opened for reading and positioned in the
intended chunk. This method does not scan for a chunk type or ID.

Result

IFFERR_EOF if there is no current chunk; IFFERR_NOMEM if temporary
buffer allocation fails; a negative ReadChunkBytes() error on read failure;
otherwise 0, including incomplete or partially failed imports.

Notes

The handle remains caller-owned. The dispatcher holds an exclusive
semaphore throughout reading and insertion. I/O can block.

Bugs

The method ignores Add failures. It stops without an error when a record
length exceeds the remaining bytes, and ignores fewer than eight trailing
bytes. It does not roll back records already imported or distinguish these
conditions from a complete import.

See Also

MUIM_Dataspace_WriteIFF, MUIM_Dataspace_Add

MUIM_Dataspace_Remove

Synopsis

IPTR result = DoMethod(obj, MUIM_Dataspace_Remove, id);

Function

Unlink and free the first record with the specified identifier.

Inputs

id - ULONG identifier to remove.

Result

1 if a record was removed; 0 if no record matched.

Notes

The dispatcher holds an exclusive semaphore lock. A successful removal
invalidates all borrowed pointers to that record.

See Also

MUIM_Dataspace_Find, MUIM_Dataspace_Add

MUIM_Dataspace_WriteIFF

Synopsis

LONG result = (LONG)DoMethod(obj, MUIM_Dataspace_WriteIFF,
                            (IPTR)handle, type, id);

Function

Push an IFF chunk, write records in current list order, then pop the
chunk. Each record contains a big-endian 32-bit identifier and length
followed by the unchanged payload bytes. No per-record padding is added
by Dataspace.

Inputs

handle - Caller-owned IFF handle opened for writing.
type - Type passed unchanged to PushChunk().
id - Chunk identifier passed unchanged to PushChunk().

Result

0 after a successful PopChunk(); otherwise the PushChunk() error,
a negative WriteChunkBytes() result, or the PopChunk() error.

Notes

The dispatcher holds an exclusive semaphore throughout the operation;
I/O can block. Internal identifier and length fields are temporarily
converted in place and restored after each write. Do not access the
dataspace concurrently outside its locking discipline.

Bugs

A negative record-write result returns without popping the chunk.
Nonnegative short writes are not checked against the requested size.
Failure can leave partial output; no rollback is performed.

See Also

MUIM_Dataspace_ReadIFF