dx::coremidi::stream< device_t, circular_t > Class Template Reference

one source or destination: the in side writes what the endpoint's callback delivers into the ring at the moment each packet carries and never stalls - a full ring drops and counts - while the out side's own thread reads whole packets and hands them to CoreMIDI at their own timestamps, which schedules what is still due More...

#include <dx_coremidi_device.h>

Inheritance diagram for dx::coremidi::stream< device_t, circular_t >:

Collaboration diagram for dx::coremidi::stream< device_t, circular_t >:

Public Types
typedef struct device_t::desc::stream	desc
typedef event< user >	event_t

Public Member Functions
stream &	attach (channel_t **[2], const std::vector< bool > &, direction::direction)
	the pin passes its own direction: a stream shared by two pins carries none of its own
virtual bool	encoder (dx::stream::encoder::index::type, unsigned int, float)
void	exception (const class exception &exception, bool filtered=false) const noexcept override
void	flush ()
void	info (std::ostream &os) noexcept override
virtual void	initialize ()
void	launch () override
uint64_t	lost () const noexcept
	the words CoreMIDI had no room for in the ring
	operator dx::midi::ump::circular * () const noexcept
dx::midi::ump::circular *	operator-> () const noexcept
void	receive (const ::MIDIEventList &list) noexcept
	receive Universal MIDI Packets from the system
virtual os_result	status () noexcept
	stream (device_t &device, const decltype(super::id)&id, const super::desc &descdesc)
	creates CoreMIDI endpoint connection and attaches stream to it
virtual bool	submit (dx::stream::encoder::index::type, unsigned int, uint8_t)
	submit encoder stage to device return true if successfully submitted; if false is returned the encode state machine will not update the stage value (i.e. if the stage can't be submitted during streaming pause), given the chance to submit the stage at start().
	~stream () override

Public Attributes
struct dx::stream::stream:: { ... }	cache
dx::stream::channel::control *	control
	kernel streaming: the driver's buffer switch bookkeeping, set by attach()
event_t	data [direction::directions]
	event signalising data arrival(in) or draining(out)
dx::promoted< dx::stream::format >	format
	the container this stream's ring runs: class and width its participants agreed on
const decltype(desc::target.idx())	id
uint32_t	latency
decltype(device_t::samplerate) &	samplerate
bool	ticking
	the tick's own view of this stream's session: set by the run hook once the ring stands, cleared by the halt hook before the session ends - a plain flag, the tick must never block on a promoted's transition

Protected Member Functions
virtual void	alloc (size_t size, bool free=true)
void	deposit (int64_t timestamp, const uint32_t *words, uint32_t count) noexcept
	a run of words into the ring, stamped at the moment they arrived: dropped where the ring is full, never stalling the endpoint's thread
virtual void	free () noexcept
	overrides may release further alloc()-acquired resources (request buffers, isoc pools, shared-memory attachments) alongside circular; called only from alloc()'s own self-cleanup or the destructor - never from halt()/stop(), so everything alloc() acquires stays live for the object's full lifetime
void	send (const dx::midi::ump::packet *packet, uint64_t count)
	the packets of one run to the endpoint, every one at its own moment CoreMIDI schedules what is due later itself, so a packet keeps the frame it was written at; a list that is full goes as it stands and the packet opens the next one.
void	transmit () noexcept
	circular data driven streaming out thread

Protected Attributes
dx::midi::ump::circular *	circular
	allocated once by initialize()/alloc(); released only by free()
::MIDIEndpointRef	endpoint {}
::MIDIPortRef	port {}
::MIDIProtocolID	protocol = ::kMIDIProtocol_1_0
	what the port speaks: MIDI 1.0 in Universal MIDI Packets, so a legacy endpoint is translated by CoreMIDI and a MIDI 2.0 one keeps its own words

Private Member Functions
reference &	initialize (::CFStringRef cf_object, bool retain=true)

Static Private Member Functions
::CFTypeID	id () noexcept

Detailed Description

template<typename device_t, typename circular_t = dx::midi::ump::circular>
class dx::coremidi::stream< device_t, circular_t >

one source or destination: the in side writes what the endpoint's callback delivers into the ring at the moment each packet carries and never stalls - a full ring drops and counts - while the out side's own thread reads whole packets and hands them to CoreMIDI at their own timestamps, which schedules what is still due

Member Typedef Documentation

desc

typedef struct device_t::desc::stream dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::desc

inherited

event_t

typedef event<user> dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::event_t

inherited

Constructor & Destructor Documentation

stream()

template<typename device_t, typename circular_t = dx::midi::ump::circular>

dx::coremidi::stream< device_t, circular_t >::stream ( device_t & device, const decltype(super::id)& id, const super::desc & desc )

inline

creates CoreMIDI endpoint connection and attaches stream to it

The port speaks Universal MIDI Packets (MIDIInputPortCreateWithProtocol, MIDISendEventList), which CoreMIDI has since macOS 11; an older system has no MIDI endpoint of this client.

the ring reset, composed with the data-driven OUT stream's own transmit thread

Here is the call graph for this function:

Here is the caller graph for this function:

~stream()

template<typename device_t, typename circular_t = dx::midi::ump::circular>

dx::coremidi::stream< device_t, circular_t >::~stream ( )

inlineoverride

Here is the call graph for this function:

Member Function Documentation

alloc()

virtual void dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::alloc ( size_t size, bool free = true )

inlineprotectedvirtualinherited

attach()

stream & dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::attach ( channel_t ** [2], const std::vector< bool > & , direction::direction  )

inlineinherited

the pin passes its own direction: a stream shared by two pins carries none of its own

deposit()

template<typename device_t, typename circular_t = dx::midi::ump::circular>

void dx::coremidi::stream< device_t, circular_t >::deposit ( int64_t timestamp, const uint32_t * words, uint32_t count )

inlineprotectednoexcept

a run of words into the ring, stamped at the moment they arrived: dropped where the ring is full, never stalling the endpoint's thread

Here is the call graph for this function:

Here is the caller graph for this function:

encoder()

virtual bool dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::encoder ( dx::stream< device_t, dx::midi::ump::circular >::encoder::index::type , unsigned int , float  )

inlinevirtualinherited

exception()

void dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::exception ( const class exception & exception, bool filtered = false ) const

inlineoverridenoexceptinherited

flush()

void dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::flush ( )

inlineinherited

free()

virtual void dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::free ( )

inlineprotectedvirtualnoexceptinherited

overrides may release further alloc()-acquired resources (request buffers, isoc pools, shared-memory attachments) alongside circular; called only from alloc()'s own self-cleanup or the destructor - never from halt()/stop(), so everything alloc() acquires stays live for the object's full lifetime

info()

void dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::info ( std::ostream< device_t, dx::midi::ump::circular > & os )

inlineoverridenoexceptinherited

initialize()

virtual void dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::initialize ( )

inlinevirtualinherited

< a shared ring takes the wider of its two directions

< this stream's own contribution: the frames its transport keeps ahead of/behind the ring

< a hosted device's ring is its host's (kernel, service, plugin) and attached as it stands - sizing it here would write the ring into a mapping of the host's making

< a fresh ring, zeroed by alloc(), takes its size here

launch()

void dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::launch ( )

inlineoverrideinherited

lost()

template<typename device_t, typename circular_t = dx::midi::ump::circular>

uint64_t dx::coremidi::stream< device_t, circular_t >::lost ( ) const

inlinenoexcept

the words CoreMIDI had no room for in the ring

Here is the call graph for this function:

Here is the caller graph for this function:

operator dx::midi::ump::circular *()

dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::operator dx::midi::ump::circular * ( ) const

inlinenoexceptinherited

operator->()

dx::midi::ump::circular * dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::operator-> ( ) const

inlinenoexceptinherited

receive()

template<typename device_t, typename circular_t = dx::midi::ump::circular>

void dx::coremidi::stream< device_t, circular_t >::receive ( const ::MIDIEventList & list )

inlinenoexcept

receive Universal MIDI Packets from the system

receive is seen from the based circular buffer perspective: the packets are written into the circular buffer (to be used by this client driver hosting application) at the moment CoreMIDI stamped them with - the host clock, which is dx::timestamp() itself, so nothing is converted.

flow control & signalisation this->data[dx::stream::direction::in] -> signals data arrival(in) It is the endpoint's own thread, so a full ring drops the words and counts them (lost()) rather than stalling MIDI reception.

Here is the call graph for this function:

send()

template<typename device_t, typename circular_t = dx::midi::ump::circular>

void dx::coremidi::stream< device_t, circular_t >::send ( const dx::midi::ump::packet * packet, uint64_t count )

inlineprotected

the packets of one run to the endpoint, every one at its own moment CoreMIDI schedules what is due later itself, so a packet keeps the frame it was written at; a list that is full goes as it stands and the packet opens the next one.

Here is the call graph for this function:

Here is the caller graph for this function:

status()

virtual os_result dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::status ( )

inlinevirtualnoexceptinherited

submit()

virtual bool dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::submit ( dx::stream< device_t, dx::midi::ump::circular >::encoder::index::type , unsigned int , uint8_t  )

inlinevirtualinherited

submit encoder stage to device return true if successfully submitted; if false is returned the encode state machine will not update the stage value (i.e. if the stage can't be submitted during streaming pause), given the chance to submit the stage at start().

transmit()

template<typename device_t, typename circular_t = dx::midi::ump::circular>

void dx::coremidi::stream< device_t, circular_t >::transmit ( )

inlineprotectednoexcept

circular data driven streaming out thread

transmit is seen from the based circular buffer perspective coremidi::stream::transmit() -> CoreMIDI MIDISendEventList: send to OS CoreMIDI MIDI Output endpoint If the receiving endpoint is an dx::coremidi::server::pin the MIDI data is received by coremidi::server::pin::receive() and there usually be used by a HW device device to send it out to its HW MIDI Output ports

flow control & signalisation this->data[dx::stream::direction::out] -> signals data draining(out) this->data[dx::stream::direction::in] -> waits for data arrival(in) ::MIDISendEventList() controls flow by stalling when endpoint buffering would be overflowing otherwise

Here is the call graph for this function:

Member Data Documentation

cache

struct { ... } dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::cache

circular

dx::midi::ump::circular* dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::circular

protectedinherited

allocated once by initialize()/alloc(); released only by free()

control

dx::stream::channel::control* dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::control

inherited

kernel streaming: the driver's buffer switch bookkeeping, set by attach()

data

event_t dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::data[direction::directions]

inherited

event signalising data arrival(in) or draining(out)

endpoint

template<typename device_t, typename circular_t = dx::midi::ump::circular>

::MIDIEndpointRef dx::coremidi::stream< device_t, circular_t >::endpoint {}

protected

format

dx::promoted<dx::stream::format> dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::format

inherited

the container this stream's ring runs: class and width its participants agreed on

A bus that negotiates it installs its own server; without one the request stands. The seed is the desc's own pin format, so a stream that nobody contradicts runs what it was declared with.

id

const decltype(desc::target.idx()) dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::id

inherited

latency

uint32_t dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::latency

inherited

port

template<typename device_t, typename circular_t = dx::midi::ump::circular>

::MIDIPortRef dx::coremidi::stream< device_t, circular_t >::port {}

protected

protocol

template<typename device_t, typename circular_t = dx::midi::ump::circular>

::MIDIProtocolID dx::coremidi::stream< device_t, circular_t >::protocol = ::kMIDIProtocol_1_0

protected

what the port speaks: MIDI 1.0 in Universal MIDI Packets, so a legacy endpoint is translated by CoreMIDI and a MIDI 2.0 one keeps its own words

samplerate

decltype(device_t::samplerate) & dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::samplerate

inherited

ticking

bool dx::stream::stream< device_t, dx::midi::ump::circular, control<object<device_t>>, event<user> >::ticking

inherited

the tick's own view of this stream's session: set by the run hook once the ring stands, cleared by the halt hook before the session ends - a plain flag, the tick must never block on a promoted's transition

---

The documentation for this class was generated from the following file:

• dx_coremidi_device.h