Midas C++ API - bm_xxx functions

This page contains the full API reference for the bm_xxx event buffer functions.

For the concepts and day-to-day use, see Event buffers: overview.

For explanations and examples of using event buffers from code, see Event buffers: programming.

Event Buffer Functions (bm_xxx)

Functions

bm_check_buffers

INT bm_check_buffers()

Check if any requested event is waiting in a buffer

Returns:

INT –
TRUE More events are waiting
FALSE No more events are waiting

Declared in include/midas.h:1821, defined in src/midas.cxx:11156

bm_close_all_buffers

INT bm_close_all_buffers()

Close all open buffers

Returns:

INT –
BM_SUCCESS

Declared in include/midas.h:1784, defined in src/midas.cxx:7278

bm_close_buffer

INT bm_close_buffer(INT buffer_handle)

Closes an event buffer previously opened with bm_open_buffer().

Parameters:

buffer_handle (INT) –
buffer handle

Returns:

INT –
BM_SUCCESS, BM_INVALID_HANDLE

Declared in include/midas.h:1783, defined in src/midas.cxx:7131

bm_compose_event

INT bm_compose_event(EVENT_HEADER * event_header, short int event_id, short int trigger_mask, DWORD data_size, DWORD serial)

Compose a Midas event header. An event header can usually be set-up manually or through this routine. If the data size of the event is not known when the header is composed, it can be set later with event_header->data-size = <...> Following structure is created at the beginning of an event

typedef struct {
 short int     event_id;
 short int     trigger_mask;
 DWORD         serial_number;
 DWORD         time_stamp;
 DWORD         data_size;
} EVENT_HEADER;

char event[1000];
 bm_compose_event((EVENT_HEADER *)event, 1, 0, 100, 1);
  (event+sizeof(EVENT_HEADER)) = <...>

Parameters:

event_header (EVENT_HEADER *) –
pointer to the event header
event_id (short int) –
event ID of the event
trigger_mask (short int) –
trigger mask of the event
data_size (DWORD) –
size if the data part of the event in bytes
serial (DWORD) –
serial number

Returns:

INT –
BM_SUCCESS

Declared in include/midas.h:1789, defined in src/midas.cxx:8355

bm_compose_event_threadsafe

INT bm_compose_event_threadsafe(EVENT_HEADER *event_header, short int event_id, short int trigger_mask, DWORD data_size, DWORD *serial)

Declared in include/midas.h:1790, defined in src/midas.cxx:8366

bm_delete_request

INT bm_delete_request(INT request_id)

Deletes an event request previously done with bm_request_event(). When an event request gets deleted, events of that requested type are not received any more. When a buffer is closed via bm_close_buffer(), all event requests from that buffer are deleted automatically

Parameters:

request_id (INT) –
request identifier given by bm_request_event()

Returns:

INT –
BM_SUCCESS, BM_INVALID_HANDLE

Declared in include/midas.h:1806, defined in src/midas.cxx:8658

bm_empty_buffers

INT bm_empty_buffers()

Clears event buffer and cache. If an event buffer is large and a consumer is slow in analyzing events, events are usually received some time after they are produced. This effect is even more experienced if a read cache is used (via bm_set_cache_size()). When changes to the hardware are made in the experience, the consumer will then still analyze old events before any new event which reflects the hardware change. Users can be fooled by looking at histograms which reflect the hardware change many seconds after they have been made.

To overcome this potential problem, the analyzer can call bm_empty_buffers() just after the hardware change has been made which skips all old events contained in event buffers and read caches. Technically this is done by forwarding the read pointer of the client. No events are really deleted, they are still visible to other clients like the logger.

Note that the front-end also contains write buffers which can delay the delivery of events. The standard front-end framework mfe.c reduces this effect by flushing all buffers once every second.

Returns:

INT –
BM_SUCCESS

Declared in include/midas.h:1820, defined in src/midas.cxx:11442

bm_flush_cache

INT bm_flush_cache(INT buffer_handle, int timeout_msec)

Declared in include/midas.h:1818, defined in src/midas.cxx:10296

bm_get_buffer_handle

INT bm_get_buffer_handle(const char *buffer_name, INT * buffer_handle)

If buffer is already open, return it's handle

Parameters:

buffer_name (const char *) –
buffer name
buffer_handle (INT *)

Returns:

INT –
BM_SUCCESS, BM_NOT_FOUND

Declared in include/midas.h:1782, defined in src/midas.cxx:7110

bm_match_event

INT bm_match_event(short int event_id, short int trigger_mask, const EVENT_HEADER *pevent)

Check if an event matches a given event request by the event id and trigger mask

Parameters:

event_id (short int) –
Event ID of request
trigger_mask (short int) –
Trigger mask of request
pevent (const EVENT_HEADER *) –
Pointer to event to check

Returns:

INT –
TRUE if event matches request

Declared in include/midas.h:1791, defined in src/midas.cxx:6048

bm_open_buffer

INT bm_open_buffer(const char *buffer_name, INT buffer_size, INT * buffer_handle)

Open an event buffer. Two default buffers are created by the system. The "SYSTEM" buffer is used to exchange events and the "SYSMSG" buffer is used to exchange system messages. The name and size of the event buffers is defined in midas.h as EVENT_BUFFER_NAME and DEFAULT_BUFFER_SIZE. Following example opens the "SYSTEM" buffer, requests events with ID 1 and enters a main loop. Events are then received in process_event()

#include <stdio.h>
#include "midas.h"
void process_event(HNDLE hbuf, HNDLE request_id, EVENT_HEADER *pheader, void *pevent)
{
  printf("Received event #%d\r",
  pheader->serial_number);
}
main()
{
  INT status, request_id;
  HNDLE hbuf;
  status = cm_connect_experiment("pc810", "Sample", "Simple Analyzer", NULL);
  if (status != CM_SUCCESS)
  return 1;
  bm_open_buffer(EVENT_BUFFER_NAME, DEFAULT_BUFFER_SIZE, &hbuf);
  bm_request_event(hbuf, 1, TRIGGER_ALL, GET_ALL, request_id, process_event);

  do
  {
   status = cm_yield(1000);
  } while (status != RPC_SHUTDOWN && status != SS_ABORT);
  cm_disconnect_experiment();
  return 0;
}

Parameters:

buffer_name (const char *) –
Name of buffer
buffer_size (INT) –
Default size of buffer in bytes. Can by overwritten with ODB value
buffer_handle (INT *) –
Buffer handle returned by function

Returns:

INT –
BM_SUCCESS, BM_CREATED
BM_NO_SHM Shared memory cannot be created
BM_NO_SEMAPHORE Semaphore cannot be created
BM_NO_MEMORY Not enough memory to create buffer descriptor
BM_MEMSIZE_MISMATCH Buffer size conflicts with an existing buffer of different size
BM_INVALID_PARAM Invalid parameter

Declared in include/midas.h:1781, defined in src/midas.cxx:6743

bm_poll_event

INT bm_poll_event()

Poll an event from a remote server. Gets called by rpc_client_dispatch() and by cm_yield()

Returns:

BM_SUCCESS –
At least one event was received and dispatched
BM_ASYNC_RETURN –
No events received
SS_ABORT –
Network connection broken

Declared in include/midas.h:1819, defined in src/midas.cxx:11328

bm_receive_event

INT bm_receive_event(INT buffer_handle, void *destination, INT * buf_size, int timeout_msec)

Receives events directly. This function is an alternative way to receive events without a main loop.

It can be used in analysis systems which actively receive events, rather than using callbacks. A analysis package could for example contain its own command line interface. A command like "receive 1000 events" could make it necessary to call bm_receive_event() 1000 times in a row to receive these events and then return back to the command line prompt. The according bm_request_event() call contains NULL as the callback routine to indicate that bm_receive_event() is called to receive events.

#include <stdio.h>
#include "midas.h"
void process_event(EVENT_HEADER *pheader)
{
 printf("Received event #%d\r",
 pheader->serial_number);
}
main()
{
  INT status, request_id;
  HNDLE hbuf;
  char event_buffer[1000];
  status = cm_connect_experiment("", "Sample",
  "Simple Analyzer", NULL);
  if (status != CM_SUCCESS)
   return 1;
  bm_open_buffer(EVENT_BUFFER_NAME, DEFAULT_BUFFER_SIZE, &hbuf);
  bm_request_event(hbuf, 1, TRIGGER_ALL, GET_ALL, request_id, NULL);

  do
  {
   size = sizeof(event_buffer);
   status = bm_receive_event(hbuf, event_buffer, &size, BM_NO_WAIT);
  if (status == CM_SUCCESS)
   process_event((EVENT_HEADER *) event_buffer);
   <...do something else...>
   status = cm_yield(0);
  } while (status != RPC_SHUTDOWN &&
  status != SS_ABORT);
  cm_disconnect_experiment();
  return 0;
}

Parameters:

buffer_handle (INT) –
buffer handle
destination (void *) –
destination address where event is written to
buf_size (INT *) –
size of destination buffer on input, size of event plus header on return.
timeout_msec (int) –
Wait so many millisecond for new data. Special values: BM_WAIT: wait forever, BM_NO_WAIT: do not wait, return BM_ASYNC_RETURN if no data is immediately available

Returns:

INT –
BM_SUCCESS, BM_INVALID_HANDLE
BM_TRUNCATED The event is larger than the destination buffer and was therefore truncated
BM_ASYNC_RETURN No event available

Declared in include/midas.h:1812, defined in src/midas.cxx:10852

bm_receive_event_alloc

INT bm_receive_event_alloc(INT buffer_handle, EVENT_HEADER** ppevent, int timeout_msec)

Receives events directly. This function is an alternative way to receive events without a main loop.

It can be used in analysis systems which actively receive events, rather than using callbacks. A analysis package could for example contain its own command line interface. A command like "receive 1000 events" could make it necessary to call bm_receive_event() 1000 times in a row to receive these events and then return back to the command line prompt. The according bm_request_event() call contains NULL as the callback routine to indicate that bm_receive_event() is called to receive events.

#include <stdio.h>
#include "midas.h"
void process_event(EVENT_HEADER *pheader)
{
 printf("Received event #%d\r",
 pheader->serial_number);
}
main()
{
  INT status, request_id;
  HNDLE hbuf;
  char event_buffer[1000];
  status = cm_connect_experiment("", "Sample",
  "Simple Analyzer", NULL);
  if (status != CM_SUCCESS)
   return 1;
  bm_open_buffer(EVENT_BUFFER_NAME, DEFAULT_BUFFER_SIZE, &hbuf);
  bm_request_event(hbuf, 1, TRIGGER_ALL, GET_ALL, request_id, NULL);

  do
  {
   size = sizeof(event_buffer);
   status = bm_receive_event(hbuf, event_buffer, &size, BM_NO_WAIT);
  if (status == CM_SUCCESS)
   process_event((EVENT_HEADER *) event_buffer);
   <...do something else...>
   status = cm_yield(0);
  } while (status != RPC_SHUTDOWN &&
  status != SS_ABORT);
  cm_disconnect_experiment();
  return 0;
}

Parameters:

buffer_handle (INT) –
buffer handle
ppevent (EVENT_HEADER**) –
pointer to the received event pointer, event pointer should be free()ed to avoid memory leak
timeout_msec (int) –
Wait so many millisecond for new data. Special values: BM_WAIT: wait forever, BM_NO_WAIT: do not wait, return BM_ASYNC_RETURN if no data is immediately available

Returns:

INT –
BM_SUCCESS, BM_INVALID_HANDLE
BM_ASYNC_RETURN No event available

Declared in include/midas.h:1816, defined in src/midas.cxx:10933

bm_receive_event_vec

INT bm_receive_event_vec(INT buffer_handle, std::vector<char> *event, int timeout_msec)

Receives events directly. This function is an alternative way to receive events without a main loop.

It can be used in analysis systems which actively receive events, rather than using callbacks. A analysis package could for example contain its own command line interface. A command like "receive 1000 events" could make it necessary to call bm_receive_event() 1000 times in a row to receive these events and then return back to the command line prompt. The according bm_request_event() call contains NULL as the callback routine to indicate that bm_receive_event() is called to receive events.

#include <stdio.h>
#include "midas.h"
void process_event(EVENT_HEADER *pheader)
{
 printf("Received event #%d\r",
 pheader->serial_number);
}
main()
{
  INT status, request_id;
  HNDLE hbuf;
  char event_buffer[1000];
  status = cm_connect_experiment("", "Sample",
  "Simple Analyzer", NULL);
  if (status != CM_SUCCESS)
   return 1;
  bm_open_buffer(EVENT_BUFFER_NAME, DEFAULT_BUFFER_SIZE, &hbuf);
  bm_request_event(hbuf, 1, TRIGGER_ALL, GET_ALL, request_id, NULL);

  do
  {
   size = sizeof(event_buffer);
   status = bm_receive_event(hbuf, event_buffer, &size, BM_NO_WAIT);
  if (status == CM_SUCCESS)
   process_event((EVENT_HEADER *) event_buffer);
   <...do something else...>
   status = cm_yield(0);
  } while (status != RPC_SHUTDOWN &&
  status != SS_ABORT);
  cm_disconnect_experiment();
  return 0;
}

Parameters:

buffer_handle (INT) –
buffer handle
event (std::vector<char> *)
timeout_msec (int) –
Wait so many millisecond for new data. Special values: BM_WAIT: wait forever, BM_NO_WAIT: do not wait, return BM_ASYNC_RETURN if no data is immediately available
ppevent –
pointer to the received event pointer, event pointer should be free()ed to avoid memory leak

Returns:

INT –
BM_SUCCESS, BM_INVALID_HANDLE
BM_ASYNC_RETURN No event available

Declared in include/midas.h:1814, defined in src/midas.cxx:11011

bm_remove_event_request

INT bm_remove_event_request(INT buffer_handle, INT request_id)

Delete a previously placed request for a specific event type in the client structure of the buffer refereced by buffer_handle.

Parameters:

buffer_handle (INT) –
Handle to the buffer where the re- quest should be placed in
request_id (INT) –
Request id returned by bm_request_event

Returns:

INT –
BM_SUCCESS, BM_INVALID_HANDLE, BM_NOT_FOUND, RPC_NET_ERROR

Declared in include/midas.h:1805, defined in src/midas.cxx:8592

bm_request_event

INT bm_request_event(INT buffer_handle, short int event_id, short int trigger_mask, INT sampling_type, INT * request_id, EVENT_HANDLER *func)

Place an event request based on certain characteristics. Multiple event requests can be placed for each buffer, which are later identified by their request ID. They can contain different callback routines. Example see bm_open_buffer() and bm_receive_event()

Parameters:

buffer_handle (INT) –
buffer handle obtained via bm_open_buffer()
event_id (short int) –
event ID for requested events. Use EVENTID_ALL to receive events with any ID.
trigger_mask (short int) –
trigger mask for requested events. The requested events must have at least one bit in its trigger mask common with the requested trigger mask. Use TRIGGER_ALL to receive events with any trigger mask.
sampling_type (INT) –
specifies how many events to receive. A value of GET_ALL receives all events which match the specified event ID and trigger mask. If the events are consumed slower than produced, the producer is automatically slowed down. A value of GET_NONBLOCKING receives as much events as possible without slowing down the producer. GET_ALL is typically used by the logger, while GET_NONBLOCKING is typically used by analyzers.
request_id (INT *) –
request ID returned by the function. This ID is passed to the callback routine and must be used in the bm_delete_request() routine.
func (EVENT_HANDLER *) –
allback routine which gets called when an event of the specified type is received.

Returns:

INT –
BM_SUCCESS, BM_INVALID_HANDLE
BM_NO_MEMORY too many requests. The value MAX_EVENT_REQUESTS in midas.h should be increased.

Declared in include/midas.h:1792, defined in src/midas.cxx:8539

bm_send_event

INT bm_send_event(INT buffer_handle, const EVENT_HEADER* event, int unused, int timeout_msec)

Declared in include/midas.h:1807, defined in src/midas.cxx:9752

bm_send_event_sg

INT bm_send_event_sg(INT buffer_handle, int sg_n, const char* const sg_ptr[], const size_t sg_len[], int timeout_msec)

Sends an event to a buffer. This function check if the buffer has enough space for the event, then copies the event to the buffer in shared memory. If clients have requests for the event, they are notified via an UDP packet.

char event[1000];
// create event with ID 1, trigger mask 0, size 100 bytes and serial number 1
bm_compose_event((EVENT_HEADER *) event, 1, 0, 100, 1);

// set first byte of event
 (event+sizeof(EVENT_HEADER)) = <...>
#include <stdio.h>
#include "midas.h"
main()
{
 INT status, i;
 HNDLE hbuf;
 char event[1000];
 status = cm_connect_experiment("", "Sample", "Producer", NULL);
 if (status != CM_SUCCESS)
 return 1;
 bm_open_buffer(EVENT_BUFFER_NAME, DEFAULT_BUFFER_SIZE, &hbuf);

 // create event with ID 1, trigger mask 0, size 100 bytes and serial number 1
 bm_compose_event((EVENT_HEADER *) event, 1, 0, 100, 1);

 // set event data
 for (i=0 ; i<100 ; i++)
  (event+sizeof(EVENT_HEADER)+i) = i;
 // send event
 bm_send_event(hbuf, event, 100+sizeof(EVENT_HEADER), BM_WAIT);
 cm_disconnect_experiment();
 return 0;
}

Parameters:

buffer_handle (INT) –
Buffer handle obtained via bm_open_buffer()
sg_n (int)
sg_ptr (const char* const[])
sg_len (const size_t[])
timeout_msec (int) –
Timeout waiting for free space in the event buffer. If BM_WAIT, wait forever. If BM_NO_WAIT, the function returns immediately with a value of BM_ASYNC_RETURN without writing the event to the buffer
source –
Address of event buffer
buf_size –
Size of event including event header in bytes

Returns:

INT –
BM_SUCCESS, BM_INVALID_HANDLE, BM_INVALID_PARAM
BM_ASYNC_RETURN Routine called with timeout_msec == BM_NO_WAIT and buffer has not enough space to receive event
BM_NO_MEMORY Event is too large for network buffer or event buffer. One has to increase the event buffer size "/Experiment/Buffer sizes/SYSTEM" and/or /Experiment/MAX_EVENT_SIZE in ODB.

Declared in include/midas.h:1811, defined in src/midas.cxx:9852

bm_send_event_vec

Note: this function has 2 different signatures.

bm_send_event_vec

INT bm_send_event_vec(INT buffer_handle, const std::vector<char>& event, int timeout_msec)

Declared in include/midas.h:1809, defined in src/midas.cxx:9779

bm_send_event_vec

INT bm_send_event_vec(INT buffer_handle, const std::vector<std::vector<char>>& event, int timeout_msec)

Declared in include/midas.h:1810, defined in src/midas.cxx:9786

bm_set_cache_size

INT bm_set_cache_size(INT buffer_handle, size_t read_size, size_t write_size)

Modifies buffer cache size. Without a buffer cache, events are copied to/from the shared memory event by event.

To protect processed from accessing the shared memory simultaneously, semaphores are used. Since semaphore operations are CPU consuming (typically 50-100us) this can slow down the data transfer especially for small events. By using a cache the number of semaphore operations is reduced dramatically. Instead writing directly to the shared memory, the events are copied to a local cache buffer. When this buffer is full, it is copied to the shared memory in one operation. The same technique can be used when receiving events.

The drawback of this method is that the events have to be copied twice, once to the cache and once from the cache to the shared memory. Therefore it can happen that the usage of a cache even slows down data throughput on a given environment (computer type, OS type, event size). The cache size has therefore be optimized manually to maximize data throughput.

Parameters:

buffer_handle (INT) –
buffer handle obtained via bm_open_buffer()
read_size (size_t) –
cache size for reading events in bytes, zero for no cache
write_size (size_t) –
cache size for writing events in bytes, zero for no cache

Returns:

INT –
BM_SUCCESS, BM_INVALID_HANDLE, BM_NO_MEMORY, BM_INVALID_PARAM

Declared in include/midas.h:1788, defined in src/midas.cxx:8214

bm_skip_event

INT bm_skip_event(INT buffer_handle)

Skip all events in current buffer.

Useful for single event displays to see the newest events

Parameters:

buffer_handle (INT) –
Handle of the buffer. Must be obtained via bm_open_buffer.

Returns:

INT –
BM_SUCCESS, BM_INVALID_HANDLE, RPC_NET_ERROR

Declared in include/midas.h:1817, defined in src/midas.cxx:11076

bm_write_statistics_to_odb

INT bm_write_statistics_to_odb()

Close all open buffers

Returns:

INT –
BM_SUCCESS

Declared in include/midas.h:1822, defined in src/midas.cxx:7315