Main Content

inMemoryStream

Create connection to event stream hosted by MATLAB without schema processing applied

Since R2022b

expand all in page

    This object requires Streaming Data Framework for MATLAB® Production Server™.

    Description

    The inMemoryStream function creates an InMemoryStream object, which you can use to test reading from and writing to event streams hosted by MATLAB. Unlike the TestStream object, InMemoryStream objects do not apply schema processing when reading and writing timetable data. The data in an inMemoryStream object disappears when you exit MATLAB.

    Creation

    Syntax

    stream = inMemoryStream
    stream = inMemoryStream(Rows=numevents)
    stream = inMemoryStream(Duration=timespan)
    stream = inMemoryStream(___,Name=Value)

    Description

    Row-Based Event Window

    stream = inMemoryStream creates a default InMemoryStream object connected to an event stream hosted by MATLAB that does not apply schema processing. The object reads 50 stream event rows at a time.

    example

    stream = inMemoryStream(Rows=numevents) creates an InMemoryStream object that reads numevents stream event rows at a time.

    Duration-Based Event Window

    stream = inMemoryStream(Duration=timespan) creates an InMemoryStream object that reads stream events occurring during the specified timestamp span, timespan.

    Additional Options

    stream = inMemoryStream(___,Name=Value) sets event stream properties using one or more name-value arguments and any of the previous syntaxes.

    Input Arguments

    expand all

    Number of events in the event window, specified as a positive integer. Rows=numevents specifies the number of rows that a call to the readtimetable function returns. If there are less than the number of specified rows available for reading, then readtimetable times out and returns an empty timetable.

    Example: Rows=500 specifies that each call to readtimetable returns a timetable with 500 rows.

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

    Timestamp span in the event window, specified as a duration scalar. Duration=timespan determines the events that the readtimetable function returns based on their timestamp. timespan specifies the difference between the last and first timestamps of events in the event window.

    Example: Duration=minutes(1) specifies that each call to readtimetable returns a timetable that has one minute's worth of events, where the timestamp of the last event is no more than one minute later than the timestamp of the first event.

    Data Types: duration

    Properties

    expand all

    Event stream name, specified as a string scalar or character vector.

    You cannot set the value of this property or use it as an input argument during object creation.

    Example: 5cb30967-46fd-4058-8be7-704e4dbccc8d

    Data Types: string

    This property is read-only.

    Event window size, specified as a fixed amount of time (using the timespan argument) or a fixed number of messages (using the numevents argument).

    Data Types: duration | single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

    Strategy to wait for a response from the stream, specified as one of these values:

    • "Size" — Client prioritizes filling the event window. Using this strategy, the client might wait longer than the RequestTimeout time period as long as it is still receiving the expected number of messages. The default number of messages is 50. If the client receives no messages within the RequestTimeout time period, it no longer waits.

    • "Time" — Client strictly adheres to the RequestTimeout limit, even if it has not received the expected number of messages. RequestTimeout specifies the amount of time the stream object waits between receiving events. If the stream is actively receiving data, it does not time out during that operation.

    Note

    This object does not implement the ReadLimit property and does not have a RequestTimeout property. It is provided for compatibility with other stream connector objects. By setting the wait strategy in this object, you can more easily update your code to switch between objects that do implement this property, such as KafkaStream.

    Unit of event timestamp, specified as one of these values:

    • "Milliseconds"

    • "Seconds"

    • "Minutes"

    • "Hours"

    • "Days"

    Interpret the event timestamp as the number of corresponding units before or after the UNIX® epoch.

    Data Types: string | char

    Event Key and Body Encoding

    Name of the key variable in the event stream, specified as a string scalar or character vector.

    Data Types: string | char

    Character encoding format used to interpret the bits in an event key, specified as one of the following:

    • utf8 — UTF-8 encoding format

    • utf16 — UTF-16 encoding format

    • base64— Base 64 encoding format

    • uint8 — Eight-bit unsigned binary bytes

    If KeyEncoding is utf8 or utf16, then the KeyType property must be text. If KeyEncoding is base64 or uint8, then KeyType must be one of the numeric encoding formats.

    Character encoding scheme used to interpret the bytes in an event key, specified as one of these values:

    • uint8 — One-byte unsigned integer

    • int8 — One-byte signed integer

    • uint16 — Two-byte unsigned integer

    • int16 — Two-byte signed integer

    • uint32 — Four-byte unsigned integer

    • int32 — Four-byte signed integer

    • uint64 — Eight-byte unsigned integer

    • int64 — Eight-byte signed integer

    • single — Single-precision IEEE 754 floating point number

    • double — Double-precision IEEE 754 floating point number

    • text — String

    If KeyType is text, then the KeyEncoding property must be either utf8 or utf16. If KeyType is any of the other numeric encoding formats, then KeyEncoding must be either base64 or uint8.

    Order for storing bits in the event key, specified as one of the following.

    • LittleEndian — Least significant bit is stored first

    • BigEndian — Most significant bit is stored first

    • MatchHost— Bits are stored in the same order as is used by the host computer on which the streaming data framework is running

    • NotApplicable — Not an integer key

    This property is applicable only for integer keys and not applicable to floating point or text keys.

    Character encoding format used to interpret the bits in the event body, specified as one of the following:

    • utf8 — UTF-8 encoding format

    • utf16 — UTF-16 encoding format

    • base64— Base 64 encoding format

    • uint8 — Eight-bit unsigned binary bytes

    This property determines the size and encoding of the bytes used in the event body, which are in the format specified by BodyFormat.

    Format of bytes in event body, specified as one of the following:

    • JSON — JSON string

    • Array — MATLAB array

    • Text — String data

    • Binary — Binary data

    Depending on the encoding specified by BodyEncoding, bytes can be larger than eight bits.

    Object Functions

    readtimetableRead timetable from event stream
    writetimetableWrite timetable to event stream
    seekSet read position in event stream
    previewPreview subset of events from event stream
    identifyingNameEvent stream name
    detectImportOptionsCreate import options based on event stream content
    detectExportOptionsCreate export options based on event stream content

    Examples

    collapse all

    Create an InMemoryStream object to preview events from and write events to an event stream hosted by MATLAB.

    is = inMemoryStream
    is = 

  InMemoryStream with properties:

                   Name: "7803fad7-64b3-4439-af40-1b0e139fd68a"
             WindowSize: 50
            KeyVariable: "key"
            KeyEncoding: "utf8"
                KeyType: "text"
           KeyByteOrder: "BigEndian"
           BodyEncoding: "uint8"
             BodyFormat: "Array"
              ReadLimit: "Size"
    TimestampResolution: "Milliseconds"

    Write timetable data to the event stream.

    load indoors
writetimetable(is,indoors)

    Preview data from the timetable. Unlike TestStream and KafkaStream, objects the InMemoryStream object does not include a key column to identify the event source, because the data kept in memory disappears when you exit MATLAB.

    preview(is)
    ans =

  8×2 timetable

           Time            Humidity    AirQuality
    ___________________    ________    __________

    2015-11-15 00:00:24       36           80    
    2015-11-15 01:13:35       36           80    
    2015-11-15 02:26:47       37           79    
    2015-11-15 03:39:59       37           82    
    2015-11-15 04:53:11       36           80    
    2015-11-15 06:06:23       36           80    
    2015-11-15 07:19:35       36           80    
    2015-11-15 08:32:47       37           80

    Version History

    Introduced in R2022b

    See Also

    |

    Topics